Motivation

I try to write code that will make sense to me when I revisit it months or years later. As a result, my code tends toward the verbose. This isn't to say that the efficiency suffers, per se, but rather that I make ample use of whitespace, avoid the use of syntactic sugar, and generally love all things BSD/Allman. In short, I drive my fellow programmers crazy. Wasteful, they say. I don't really see what the big deal is, though. Isn't this the reason that code formatters were invented?

Comments, on the other hand, are much more worthy of a protracted flamewar. Indentation is an easily changed personal preference. Good commenting, however, is essential to long-term code maintainability. Here there is a trade-off between personal preference and accepted industry practices. To that end, I am trying to synchronize my habits with Sun's official Javadoc recommendations.

Header

javadoc will be used to convey the purpose of each class, so a simple non-javadoc boilerplate message is all that should appear at the top each file. My license of choice is the GPL. I am a Free software advocate and RMS admirer, and therefore explicitly leave in the "or later" clause. I'll probably adopt GPLv3 when it is finalized.

/*
 * This file is part of jEAC (http://jeac.sf.net/).
 * 
 * Copyright (C) YYYY.  All rights reserved.
 * 
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License as
 * published by the Free Software Foundation; either version 2 of
 * the License, or (at your option) any later version.
 * 
 */

 package ...

 import java.*;
 import javax.*;

 import com.thirdparty.*;

 import edu.cs.indiana.eac.*;



 /**
  * ...
  *
  */
 public class...

The package declaration and imports should be separated by one blank line. Imports should by ordered as follows and end in an asterisk.

1. java/javax
2. 3rd party
3. jEAC

Each import group should be separated by one blank line. The class declaration should be separated by three blank lines.

 /**
  * One line phrase describing the class.
  * 
  * <p>A longer description of the class and its particularities.
  * This section may make use of minimal HTML formatting.
  *
  * @author    Author Name
  * @since     X.Y.Z
  *
  * @version   X.Y.Z
  *
  */

NOTE: I'm not 100% sure about the use of the @version tag yet. Obviously we would like to convey some kind of differential information, but it is not clear how best do this. In any event, @version is local to the particular block of code while @since is in reference to the overall release.

Methods

/**
 * Single phrase summary that describes the method succinctly.
 *
 * <p>An expanded version that describes things in greater detail.  The summary
 * should always appear on its own line.  This is a personal preference.  I think
 * it improves scanability if paragraph tags are on the same line as the text
 * block
 * 
 * @param var    A short phrase describing the variable and its purpose.  Longer 
 *               sentences can used if necessary.  The phrase should be in the 3rd 
 *               person, and contrary to Sun, be capitalized and end in a period.
 * @param var    Set to <code>true</code> if it is a boolean.
 * @return       The return value, in phrase form.
 * @throws var   Description of the exception.  Indent and align all entries three
 *               spaces from the longest parameter name.
 *
 * @author       Author Name
 * @since        X.Y.Z
 * 
 */

NOTE: While the @author is not valid for methods, I include them anyway. It helps to keep track of where contributions come from.

Comments

Public field - upper case; punctuated:

/** Field description, fit for Javadoc'ing. */

Fields - lower case; no punctuation:

/* field description */

Code description - lower case; no punctuation:

// one line explanation

Block description - sentence format; verbose:

/*
 * Long, multi-line description of what is happening and why it matters
 * Notice the empty comment line before the closing star-slash.
 *
 */

Delimiters (eight newlines):

/* =========================[ Listeners, etc. ]========================= */

Delimiters (four newlines):

/* -------------------------[ Generic class methods ]------------------------- */

/* -------------------------[ Specific methods ]------------------------- */

/* -------------------------[ Get/set methods ]------------------------- */

Fields

1. CONSTANT_DECLARATIONS;
2. defaultVariables, modified through API calls
3. otherFields, to be initialized by the constructor

Miscellaneous

• There should be one blank line before the closing class brace.
• Methods should be organized as such:
  1. Generic methods: constructor, main, Java-overrides
  2. Specific class methods, alphabetized
  3. Get/set methods (all alphabetized):
     1. is-methods
     2. get/set pairs
  4. Anonymous classes, alphabetized

In progress

I've developed a few conventions over time that I am not sure about yet. It just happens to be the way I have been doing things:

• I have no line-wrapping policy. Long lines are obviously sub-optimal, but there's no real rhyme or reason to breaking up long lines.
  • I try to keep my block comments under 80 characters wide, but that's not a hard rule
• get/set methods should NOT be condensed to one line
• set methods should prefix their variables with this; get methods should not
  • In fact, I use this fairly inconsistently

TODO

1. Incorporate automatically generated revision strings [1]
2. Publish Eclipse source formatter