stratos-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Lahiru Sandaruwan <lahi...@wso2.com>
Subject Re: [Discuss] Coding Standards & Best Practices Guidelines
Date Thu, 02 Oct 2014 05:58:23 GMT
+1 for 120.

On Thu, Oct 2, 2014 at 11:19 AM, Isuru Perera <isurup@wso2.com> wrote:

> Hi Nirmal,
>
> Sorry for the delay! I needed some time to go through the coding
> guidelines in WSO2 and other Apache project.
>
> All,
>
> Since everyone agrees on 4 spaces, we will configure that accordingly. My
> next concern is that 100 columns for a line is too short.
>
> Most of other projects use 120 columns for the line width.
>
> For example:
> http://maven.apache.org/developers/conventions/code.html
> https://airavata.apache.org/development/source.html
> http://onami.apache.org/committers/codestyle.html
>
> However I think it's better if we can have at least 160 columns for a line.
>
> There are some projects, which use 160 columns. :)
> https://accumulo.apache.org/source.html
>
> So, WDYT?
>
>
> On Wed, Oct 1, 2014 at 5:15 PM, Sajith Kariyawasam <sajith@wso2.com>
> wrote:
>
>> I came up with the attached code format profile for Eclipse. This is
>> based on the  Eclipse (built in) profile, and I modified lineSplit from 80
>> to 100 and 4 Space indentation. Other default settings seems OK to me.
>>
>> Please share your thoughts
>>
>> Thanks,
>> Sajith
>>
>> On Wed, Oct 1, 2014 at 4:47 PM, Nirmal Fernando <nirmal070125@gmail.com>
>> wrote:
>>
>>> Guys,
>>>
>>> Did you all manage to create the formatter profiles?
>>>
>>> On Tue, Sep 23, 2014 at 11:59 AM, Nirmal Fernando <
>>> nirmal070125@gmail.com> wrote:
>>>
>>>> Thanks for the reminder Imesh. I've created a Jira for this
>>>> https://issues.apache.org/jira/browse/STRATOS-813
>>>>
>>>> On Tue, Sep 23, 2014 at 10:31 AM, Imesh Gunaratne <imesh@apache.org>
>>>> wrote:
>>>>
>>>>> It's nice to see everyone is focusing on $subject. I just went through
>>>>> the latest Sonar findings and seems like there are nearly 270 critical
>>>>> issues:
>>>>>
>>>>>
>>>>> https://analysis.apache.org/drilldown/issues/org.apache.stratos:stratos-parent?severity=CRITICAL
>>>>>
>>>>> We can go through the list and fix these issues, on the next build
>>>>> Sonar listing will get updated.
>>>>>
>>>>> On Mon, Sep 22, 2014 at 7:32 AM, Akila Ravihansa Perera <
>>>>> ravihansa@wso2.com> wrote:
>>>>>
>>>>>> On Mon, Sep 22, 2014 at 4:39 PM, Isuru Perera <isurup@wso2.com>
>>>>>> wrote:
>>>>>> > Hi everyone,
>>>>>> >
>>>>>> > I think we should agree on whether we should use tabs or spaces
for
>>>>>> the
>>>>>> > indentation.
>>>>>> >
>>>>>> > I'm suggesting that we should use 4 spaces for the indentation
and
>>>>>> > completely avoid tabs in our code.
>>>>>>
>>>>>> +1
>>>>>>
>>>>>> Tabs can mess up the code when working with different developer
>>>>>> environments.
>>>>>>
>>>>>>
>>>>>> >
>>>>>> > I can help to come up with an Eclipse Formatter profile. We
should
>>>>>> also
>>>>>> > format the entire code base in a single commit after we agree
on
>>>>>> our coding
>>>>>> > standards.
>>>>>>
>>>>>> Great! I can work on a IntelliJ Idea Formatting profile.
>>>>>>
>>>>>> >
>>>>>> > WDYT?
>>>>>> >
>>>>>> > Thanks!
>>>>>> >
>>>>>> > Best Regards,
>>>>>> >
>>>>>> >
>>>>>> > On Tue, Sep 16, 2014 at 11:52 AM, Lakmal Warusawithana <
>>>>>> lakmal@wso2.com>
>>>>>> > wrote:
>>>>>> >>
>>>>>> >> Hi,
>>>>>> >>
>>>>>> >> This is the guideline we used in WSO2, shall we have a look
and see
>>>>>> >> whether we can use the same.  Please share your thoughts.
After we
>>>>>> finalised
>>>>>> >> will put this into wiki and make it as common guide line.
>>>>>> >>
>>>>>> >> Comments
>>>>>> >>
>>>>>> >> Doc comments
>>>>>> >>
>>>>>> >> All classes and all methods/functions MUST have doc comments
>>>>>> >>
>>>>>> >> Explain each parameter, return type and assumptions made
>>>>>> >>
>>>>>> >> Line comments
>>>>>> >>
>>>>>> >> In case you have complex logic, explain any genius logic,
>>>>>> rationale for
>>>>>> >> doing something
>>>>>> >>
>>>>>> >>
>>>>>> >> Logging
>>>>>> >>
>>>>>> >> Log then and there
>>>>>> >>
>>>>>> >> With ample local information and context
>>>>>> >>
>>>>>> >> Remember logs are for users. Make them meaningful, readable
and
>>>>>> also make
>>>>>> >> sure you spell check (ispell)
>>>>>> >>
>>>>>> >> Use correct log level, e.g do not log errors as warnings
or vice
>>>>>> versa
>>>>>> >>
>>>>>> >> Remember to log the error before throwing an exception
>>>>>> >>
>>>>>> >>
>>>>>> >> Logic
>>>>>> >>
>>>>>> >> Make your genius code readable
>>>>>> >>
>>>>>> >> Use meaningful variable names. Remember, compilers can handle
long
>>>>>> >> variable names
>>>>>> >>
>>>>>> >> ________________________________
>>>>>> >>
>>>>>> >> Variables declared in locality, as an when required
>>>>>> >>
>>>>>> >> The underscore character should be used only when declaring
>>>>>> constants, and
>>>>>> >> should not be used anywhere else in Java code
>>>>>> >>
>>>>>> >> Make sure the function/method names are self descriptive
>>>>>> >>
>>>>>> >> One should be able explain a function/method using a single
>>>>>> sentence
>>>>>> >> without conjunctions (that is no and/or in description)
>>>>>> >>
>>>>>> >> Have proper separation of concerns
>>>>>> >>
>>>>>> >> Check if you do multiple things in a function
>>>>>> >>
>>>>>> >> Too many parameters are smelly, indicates that something
is wrong
>>>>>> >>
>>>>>> >> Use  variables to capture status and return at the end whenever
>>>>>> possible
>>>>>> >>
>>>>>> >> Avoid status returning from multiple places, that makes
code less
>>>>>> readable
>>>>>> >>
>>>>>> >> Be consistent in managing state e.g. Initialize to FALSE
and set
>>>>>> to TRUE
>>>>>> >> everywhere else
>>>>>> >>
>>>>>> >> Where does that if block end, or what block did you end
right now?
>>>>>> Have a
>>>>>> >> comment at end of a block at }
>>>>>> >>
>>>>>> >> Use if statements rationally, ensure the behavior is homogeneous
>>>>>> >>
>>>>>> >> In case of returning a collection, must return an empty
collection
>>>>>> and not
>>>>>> >> null (or NULL)
>>>>>> >>
>>>>>> >> Do not use interfaces to declare constants. Use a final
class with
>>>>>> public
>>>>>> >> static final attributes and a private constructor.
>>>>>> >>
>>>>>> >> Always use braces to surround code blocks ({}) even if it
is a
>>>>>> single
>>>>>> >> line.
>>>>>> >>
>>>>>> >> Break code into multiple lines if it exceeds 100 columns
>>>>>> >>
>>>>>> >> Align method parameters, exception etc. in order to improve
>>>>>> readability.
>>>>>> >> Use the settings in your IDE to do this.
>>>>>> >>
>>>>>> >> Be sure to define, who should catch an exception when throwing
one
>>>>>> >>
>>>>>> >> Be sure to catch those exceptions that you can handle
>>>>>> >>
>>>>>> >> Do not use string literals in the code, instead declare
constants
>>>>>> and use
>>>>>> >> them, constant names should be self descriptive
>>>>>> >>
>>>>>> >> Use constants already defined whenever possible, check to
see if
>>>>>> someone
>>>>>> >> already declared one, specially in base libs, like Axis2
>>>>>> >>
>>>>>> >>
>>>>>> >> Java Specific
>>>>>> >>
>>>>>> >> Coding conventions -
>>>>>> >> http://www.oracle.com/technetwork/java/codeconv-138413.html
>>>>>> >>
>>>>>> >> Only exception is line length, we use 100
>>>>>> >>
>>>>>> >> Run FindBugs on your code - http://findbugs.sourceforge.net/
>>>>>> >>
>>>>>> >> Use CONSTANT_VALUE.equals(variable_name) to avoid null pointer
>>>>>> exceptions
>>>>>> >>
>>>>>> >> IMPORTANT
>>>>>> >>
>>>>>> >> You should run FindBugs on your new code or modified code,
and
>>>>>> commit only
>>>>>> >> after fixing any bugs reported by FindBugs. It is recommended
to
>>>>>> use the
>>>>>> >> IntellijIDEA (FindBugs-IDEA) or Eclipse FindBugs plugin
to do this.
>>>>>> >>
>>>>>> >>
>>>>>> >>
>>>>>> >> --
>>>>>> >> Lakmal Warusawithana
>>>>>> >> Vice President, Apache Stratos
>>>>>> >> Director - Cloud Architecture; WSO2 Inc.
>>>>>> >> Mobile : +94714289692
>>>>>> >> Blog : http://lakmalsview.blogspot.com/
>>>>>> >>
>>>>>> >
>>>>>> >
>>>>>> >
>>>>>> > --
>>>>>> > Isuru Perera
>>>>>> > Senior Software Engineer | WSO2, Inc. | http://wso2.com/
>>>>>> > Lean . Enterprise . Middleware
>>>>>> >
>>>>>> > about.me/chrishantha
>>>>>>
>>>>>>
>>>>>>
>>>>>> --
>>>>>> Akila Ravihansa Perera
>>>>>> Software Engineer, WSO2
>>>>>>
>>>>>> Blog: http://ravihansa3000.blogspot.com
>>>>>>
>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> Imesh Gunaratne
>>>>>
>>>>> Technical Lead, WSO2
>>>>> Committer & PMC Member, Apache Stratos
>>>>>
>>>>
>>>>
>>>>
>>>> --
>>>> Best Regards,
>>>> Nirmal
>>>>
>>>> Nirmal Fernando.
>>>> PPMC Member & Committer of Apache Stratos,
>>>> Senior Software Engineer, WSO2 Inc.
>>>>
>>>> Blog: http://nirmalfdo.blogspot.com/
>>>>
>>>
>>>
>>>
>>> --
>>> Best Regards,
>>> Nirmal
>>>
>>> Nirmal Fernando.
>>> PPMC Member & Committer of Apache Stratos,
>>> Senior Software Engineer, WSO2 Inc.
>>>
>>> Blog: http://nirmalfdo.blogspot.com/
>>>
>>
>>
>>
>> --
>> *Sajith Kariyawasam*
>>
>>
>>
>>
>>
>>
>>
>>
>> *Committer and PMC member, Apache Stratos,WSO2 Inc., http://wso2.com
>> <http://wso2.com>AMIE (SL)Mobile: +94772269575-- Isuru PereraSenior
>> Software Engineer | WSO2, Inc. | http://wso2.com/ <http://wso2.com/>Lean .
>> Enterprise . Middlewareabout.me/chrishantha <http://about.me/chrishantha> *
>>
>


-- 
--
Lahiru Sandaruwan
Committer and PMC member, Apache Stratos,
Senior Software Engineer,
WSO2 Inc., http://wso2.com
lean.enterprise.middleware

email: lahirus@wso2.com cell: (+94) 773 325 954
blog: http://lahiruwrites.blogspot.com/
twitter: http://twitter.com/lahirus
linked-in: http://lk.linkedin.com/pub/lahiru-sandaruwan/16/153/146

Mime
View raw message