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 Fri, 19 Sep 2014 11:10:26 GMT
Thanks for your feedback, Sajith!

Based on your comment shall I remove the following guideline?


   - Reformat code using the formatting option provided in the respective
   IDE.
   For example, if you are using intelliJ IDEA, navigate *Code* menu and
   click *Reformat the code *or use the keyboard shortcut as follows:
   Alt+Ctrl+L


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 Fri, Sep 19, 2014 at 3:35 PM, Sajith Kariyawasam <sajith@wso2.com> wrote:

> Hi,
>
> In formatting code, I think we need to come up with templates for both
> Eclipse and IntelliJ to make sure everyone uses the same formatting
> guidelines.
> Default formatters may be different within IDEs, and when someone
> reformats using a different formatter, the code diff will have the
> formatting diffs also, which
> makes really hard to track the code changes.
>
> @Mari  "Alt+Ctrl+L" is not the default code format shortcut in Eclipse,
> IMO if we specify a shortcut key we need to mention the IDE as well..
>
> Thanks,
> Sajith
>
> On Thu, Sep 18, 2014 at 6:19 PM, Mariangela Hills <mariangela@wso2.com>
> wrote:
>
>> Hi All,
>>
>> I added the content in [1]. Please let me know if any changed are needed.
>>
>> [1]
>> https://cwiki.apache.org/confluence/display/STRATOS/Coding+Standards+and+Best+Practices
>>
>> 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 Thu, Sep 18, 2014 at 5:14 PM, Nirmal Fernando <nirmal070125@gmail.com>
>> wrote:
>>
>>> I think we can use the general Java coding conventions
>>> http://www.oracle.com/technetwork/java/codeconvtoc-136057.html
>>>
>>> On Wed, Sep 17, 2014 at 10:30 AM, Mariangela Hills <mariangela@wso2.com>
>>> wrote:
>>>
>>>> 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/
>>>>>
>>>>>
>>>>
>>>
>>>
>>> --
>>> 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*
>

Mime
View raw message