Login | Register
My pages Projects Community openCollabNet

Axion: Developer's Guide: Style

Developer's Guide: Coding Conventions and Style Guide

In Progress.

Matters of Style

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.


Coding Conventions

  • 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());
      }



Axion - Open Source Java Database Engine
$Id: style.html,v 1.33 2007/11/15 15:09:27 rwald Exp $
Published 15 Nov 2007 at 3:07 PM GMT.