cool stuff
$URL: svn+ssh://alci@svn.forge.objectweb.org/svnroot/barracudamvc/Barracuda2/tags/2.1/WEB-INF/src_docs/developers/coding_standards.html, v125

Coding Standards

This is an effort to define some basic elements of coding style that developers should follow when contributing code. In general, we like as few rules as necessary (this is open source after all). Our goal is to keep this list of as short as possible.
  1. Start by adhering as closely as possible to the Sun coding convention (notice we do not say 'exactly'...their own code varies some too). If you can point to code in the Java source that matches your style, then we're cool with it.
     
  2. Here are some obvious things for which we expect everyone to follow. 


    A) Adhere to well recognized naming conventions:

    • class names should always be capitalized (ie. 'FooBar', not 'fooBar');
    • variable names should always start with a lower case letter (ie public String 'foo', not 'Foo');
    • constants should use all caps (ie. public static final String FOO="blah").
    • Try and conform to javabean naming conventions (set/gets).
    • Always use accessors to access members of an object (this means constants are really the only thing you should ever define as public).


    B) Try to follow well recognized design practices:

    • always initialize variables (ie. 'String fooStr = null', rather than 'String fooStr;'
    • use accessors rather than public vars to reference an object's properties from another class
    • when writing classes for a framework (like Barracuda), generally declare internal variables protected rather than private (makes it possible for other developers to extend your code)


    You get the idea.
     

  3. Documentation is important. Good code will be well designed AND documented. We should all strive to write really good, clear, understandable code. All accompanying documentation (ie. beyond what is in the code) should be captured in HTML and put in the docs directory. No raw text files please.
     
  4. When writing new code, feel free to use your style (see #1 though); when making changes to someone else's code, try and follow the existing style to keep everything readable. If the author took enough time to write a piece of code and then provide it to the community, show your appreciation by following their style when you improve their code. If it's really bad, then fix it rather than griping about it.
     
  5. When making fixes, be sure to document all your changes (see the 'Commenting changes in the code email' email) so others can easily see what you did.
     
  6. If you submit code, include test cases for it (up till now, we haven't written many test cases, but this is a high priority for us and we are working to remedy this). We use the JUnit test framework.
     
  7. Whenever you write an 'if' statement, always enclose the body of the stmt in {} unless its a one line stmt that goes on the same line as the 'if'. If you put it on a separate line, enclose it in braces. For 'for' statements, ALWAYS put the loop code in braces. This makes for maintainable code (I don't know how many times I've seen bugs where someone added a line of code inside a control block and didn't realize that there weren't enclosing braces (meaning they didn't really add it to the control block...)
     
  8. Always indent using either 4 spaces. DO NOT USE TABS IN YOUR SOURCE!!!   Windows/unix editors often vary on tabbing; most windows editors use tabs=4 spaces, whereas unix is often 8. At first we tried to be accommodating and allow both and the source quickly started to get ugly. SO...you must use spaces when submitting changes!
     
  9. Follow the instructions described in Submitting Changes when sending your work to the mailing list for review.

Additional note - For a good document on coding styles, consider Scott Ambler's Java Coding Standards standards... it's not infallible, but it's pretty darn good. I think we generally agree with much of what he says, and his paper goes a long way towards explaining why various ways of doing things are good, bad, or ugly.

 


Last Modified: 2006-01-02 21:59:13 +0100 (lun, 02 jan 2006)