|
Jakarta main
About
Overview
Features
History
License
Mail Archive
Contributors
Coding Standards
Sub-Projects
Framework
Excalibur
Phoenix
Cornerstone
Testlet
LogKit
|
Coding Standards |
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
enviroment, 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)
-
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 Jakarta Apache/Avalon 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 indention when you're constrained
to wrap a line.
-
We focus on readability over performance, at least in the first
phase, leaving source code optimization the last resource to give
out some milliseconds from my code. If the code is not performing then
it is better to re-engineer it rather than to expand loops, take
out variable declarations and such things. If the code is
performing well and you know what the core methods are then, in the
end of the process, try to give out the best from them.
-
Try to javadoc-comment all methods and public/default/protected
attributes adding code comments only when you think it's really
needed (like assumptions).
-
Variables are declared in the inner scope.
while( myListIterator.hasNext() )
{
final String myString = (String)myLstIterator.nextElement();
}
|
-
Variable names are every time descriptive. The cases where this rule is
not applied include; manipulating exceptions (only uppercase class
exception letters), loop declaring variables (mostly I use i,j,k and t)
and other established shortenings (like init() for initialize, sb for
StringBuffer etc). ie.
try
{
for( int i = 0; i < 10; i++ )
{
// some stuff
}
}
catch( final FileNotFoundException fnfe )
{
// some stuff
}
catch( final IndexOutOfBoundsException ioobe )
{
// some stuff
}
|
-
Use only String concatenation unlesss you really need
StringBuffer methods leaving to the compiler optimization
the stuff to replace it with StringBuffer, 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". That gets the object of type java.lang.Class
that corresponds to your class MyClass.
-
Have the names of all class fields start with the prefix "m_".
Example:
class MyClass
{
String m_class = MyClass.getClass();
int m_users;
}
|
Thanks for your cooperation.
-The Avalon Team
|
| by
Avalon Documentation Team, Berin Loritsch, Peter Donald, Roberto Lo Giacco, Leo Simons |
|