stratos-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mariangela Hills <mariang...@wso2.com>
Subject Re: [Discuss] Coding Standards & Best Practices Guidelines
Date Wed, 17 Sep 2014 05:00:02 GMT
Lakmal, will do! I have created a JIRA [1] to track this task.

[1] https://issues.apache.org/jira/browse/STRATOS-804

Regards,
Mariangela




*--*
Mariangela Hills
Senior Technical Writer

*WSO2, Inc.*lean.enterprise.middleware.
m: +94 773 500185
w: http://wso2.com
<http://wso2.com/events/>

On Wed, Sep 17, 2014 at 10:09 AM, Lakmal Warusawithana <lakmal@wso2.com>
wrote:

> @Mari,
>
> Can you work on all feedback and compile a wiki page?
>
> On Tue, Sep 16, 2014 at 1:11 PM, Akila Ravihansa Perera <
> ravihansa@wso2.com> wrote:
>
>> Hi,
>>
>> +1 for using this as the common guideline.
>>
>>  IMO, we should add coding styles as well. It will make the code more
>> readable and easy to understand. We might be able to get some idea
>> from Google Java style in [1]. Another style from Apache ACE project
>> in [2].
>>
>> [1] https://google-styleguide.googlecode.com/svn/trunk/javaguide.html
>> [2] https://ace.apache.org/dev-doc/coding-standards.html
>>
>> Thanks.
>>
>> On Tue, Sep 16, 2014 at 12:28 PM, Sajith Kariyawasam <sajith@wso2.com>
>> wrote:
>> > You can access Sonar dashboard for Stratos in [1], Imesh shared this in
>> the
>> > thread [Discuss] Setting up Sonar for Stratos
>> > [1]
>> >
>> https://analysis.apache.org/dashboard/index/org.apache.stratos:stratos-parent
>> >
>> > On Tue, Sep 16, 2014 at 12:15 PM, Sajith Kariyawasam <sajith@wso2.com>
>> > wrote:
>> >>
>> >> Hi all,
>> >>
>> >> I think these guidelines should align with the Sonar rules which are
>> >> already integrated with Stratos, or decide on a set of guidelines and
>> change
>> >> the Sonar rules accordingly.
>> >>
>> >> Also, IMO we should use Sonar plugin in IDE s, rather than using
>> Findbugs
>> >> / PMD etc individually..
>> >> [1]
>> >>
>> http://stackoverflow.com/questions/5479019/is-sonar-replacement-for-checkstyle-pmd-findbugs
>> >>
>> >> I assume that we can use Sonar even for managing code review stuff as
>> well
>> >> [2]
>> >> [2] http://www.sonarqube.org/effective-code-review-with-sonar/
>> >>
>> >> Thanks,
>> >> Sajith
>> >>
>> >> 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/
>> >>>
>> >>
>> >>
>> >>
>> >> --
>> >> Sajith Kariyawasam
>> >> Committer and PMC member, Apache Stratos,
>> >> WSO2 Inc., http://wso2.com
>> >> AMIE (SL)
>> >> Mobile: +94772269575
>> >>
>> >
>> >
>> >
>> > --
>> > Sajith Kariyawasam
>> > Committer and PMC member, Apache Stratos,
>> > WSO2 Inc., http://wso2.com
>> > AMIE (SL)
>> > Mobile: +94772269575
>> >
>>
>>
>>
>> --
>> Akila Ravihansa Perera
>> Software Engineer, WSO2
>>
>> Blog: http://ravihansa3000.blogspot.com
>>
>
>
>
> --
> Lakmal Warusawithana
> Vice President, Apache Stratos
> Director - Cloud Architecture; WSO2 Inc.
> Mobile : +94714289692
> Blog : http://lakmalsview.blogspot.com/
>
>

Mime
View raw message