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 <mariang...@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 <nirmal070...@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 <mariang...@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 <lak...@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 < >>>> raviha...@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 <saj...@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 < >>>>> saj...@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 < >>>>> lak...@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*
