/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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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...)
- 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!
- 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 15:59:13 -0500 (Mon, 02 Jan 2006)