In Progress.
We're not especially hard-nosed about style, but a common, consistent format helps make the Axion code base more readable and therefore manageable. Following these coding conventions, or a minimum, following the "local" style used in the file you are working with increases the ease and likelihood of your patch being applied.
General
Always indent with spaces, preferably 4 at a time. Never indent with tabs.
Use Unix (\n) linefeeds unless the file requires another format.
Axion's license should be included at the top of every file.
When reasonable, an
$
Id:
$
tag should be included in every file.
Java
As a rule, we follow Sun's
Code Conventions for the Java Programming Language
with one major exception--private
, "package" and
protected
variables
are prefixed with a single underscore ('_
').
All blocks, even one-line blocks, should include curly braces. For example, write:
if(breakhere) { break; }
never:
if(breakhere) break;
In general, Java import statements should be fully qualified (avoid the "import foo.bar.*" format) unless a rather large number of classes from the same package are being imported.
JavaDocs
The use of complete JavaDoc comments is strongly encouraged.
Java classes should include a "@version" tag, as follows:
@version$
Revision:
$
$
Date:
$
If you contribute to a Java source file, add yourself to the author list for that class. For example:
@author John Doe
or
@author <a href="mailto:john.doe@example.com">John Doe</a>
Each Java package should include a package.html
file, directly in the source tree.
Logging
We use Commons-Logging for logging. Do not use Log4J, the Java Logging APIs, or other logging frameworks directly.
By convention, we use Log
instances named after the fully specified class in which it is used.
For example, log messages generated by the class Foo
in the package org.axiondb.bar
should be named
"org.axiondb.bar.Foo
".
Be judicious about the verbosity of log messages, and of the log level used.
Be aware that when using Commons-Logging, like other logging frameworks, Java will evaluate the parameters passed to a method even if that log level is disabled. For example, given:
_log.debug("Foo is \"" + foo + "\"); _log.debug("someMethod() returns: " + someMethod());
Java will evaluate foo.toString()
and
this.someMethod()
, whether or not
the call generates any log messages. Hence unless you're
working with literal strings, wrap your logging calls with
isDebugEnabled()
or similiar methods.
For example:
if(_log.isDebugEnabled()) { _log.debug("Foo is \"" + foo + "\"); _log.debug("someMethod() returns: " + someMethod()); }