This document describes a list of coding conventions
that are required for code submissions to the project. By default,
the coding conventions for most Open Source Projects should follow
the existing coding conventions in the code that you are working
on. For example, if the bracket is on the same line as the if
statement, then you should write all your code to have that convention.
If you commit code that does not follow
these conventions and you are caught, you are responsible for
also fixing your own code.
- Brackets should begin and end on a new line. Examples:
if( foo )
{
// code here
}
try
{
// code here
}
catch( final Exception bar )
{
// code here
}
finally
{
// code here
}
while( true )
{
// code here
}
|
-
The preference is to include extra spaces
between parenthesis and expression. For example;
-
4 spaces. NO tabs. Period. We understand
that a lot of you like to use tabs, but the fact of the matter
is that in a distributed development environment, when the
cvs commit messages get sent to a mailing list, they are almost
impossible to read if you use tabs.
In Emacs-speak, this translates to the following
command: (setq-default tab-width 4 indent-tabs-mode nil)
In vim, having the following in your .vimrc
will help:
set tabstop=4
set expandtab
set list
set listchars=tab:>.
|
- Unix linefeeds for all .java source code files. Other platform
specific files should have the platform specific linefeeds.
- Javadoc SHOULD exist on all your methods. Also,
if you are working on existing code and there currently isn't
a javadoc for that method/class/variable or whatever, then you
should contribute and add it. This will improve the project
as a whole.
- The GPL license MUST be placed at the top of each
and every file.
- If you contribute to a file (code or documentation), add
yourself to the top of the file. For java files the preferred
Javadoc format is:
@author <a href="mailto:user@domain.com">John Doe</a>
|
- Indent comments on an 80 column basis and the code on a 100
column, using a two more indents when a line must be wrapped.
- We focus on readability over performance, at least initially.
Source code optimization is the last thing to be done to increase
performance. If the code is not performing then it is better
to re-engineer it rather than to expand loops, take out variable
declarations etc. When the code is stable and has a well defined
purpose and interface it may be appropriate to do source code
optimization.
- Try to javadoc all methods and variables, especially public,
protected and default access methods and member variables. Also
add code comments when you think it's necessary (like assumptions).
- Variables are declared in the inner scope.
while( myListIterator.hasNext() )
{
final String myString = (String)myListIterator.nextElement();
}
|
- Variable should be descriptive and ideally English words.
The exceptions being; loop counters (usually use i, j and k),
exceptions (use concatenation of word separating characters
- ie SocketException is abbreviated as se) and other commonly
used abbreviations (ie sb for StringBuffer).
try
{
for( int i = 0; i < 10; i++ )
{
// some stuff
}
}
catch( final FileNotFoundException fnfe )
{
// some stuff
}
catch( final IndexOutOfBoundsException ioobe )
{
// some stuff
}
|
- Use String concatenation except in extremely performance
sensitive sections. This leaves StringBuffer optimization to
the compiler. So use:
final String myString = "test " + "for " + "performances";
|
- Try not to declare a method as 'synchronized'. If a method
accesses a shared resource then surround accesses to that resource
with a synchronized block. Ideally the synchronized block should
surround the smallest possible area. For example:
public void sharedMethod()
{
String display = null;
synchronized( this )
{
display = mySharedObject.getHelloWorld();
}
System.out.println( display );
}
|
If you are within a static method, then you may have to create
a static object whose sole purpose in life is to provide the
lock you need. Alternatively you could use the Class object
for the class you are in. That is, if you're in class MyClass,
use "MyClass.class".
- Have the names of all member instance fields start with the
prefix "m_". Example:
class MyClass
{
Class m_class = MyClass.getClass();
int m_users;
}
|
Thanks for your cooperation.
-The Spumoni Team
|