Formatting Java code

This is an extrapolation of the formatting instructions in GNU's standards documentation.

New Java code for GNU Crypto should be written in "GNU style", with slight modifications for Java. The usual rules for Java code are:

• Put each class into its own file, and put that file in a sequence of directories that match that class's package. So put a class `foo.bar.Baz' into the file `foo/bar/Baz.java'.

• Package names should be lower case, and should be a single word or abbreviation.

• The basic unit of indentation is two spaces. Only spaces should be used to indent, not tabs.

• Import each class used and never write the package name before the class name, unless it is needed to avoid conflicts.

• List your imports alphabetically, and split large lists by package. Don't use the wildcard syntax unless you need to import a large number of classes from one package.

• Write variable and class names in mixed capitals, and capitalize the first letter if it is a class name. For example, a class name would look like ``ClassName'' and a variable ``variableName''.

• Section your code into logical pieces, like "Constants and fields", "Constructors", "Class methods", and "Instance methods".

  Delimit each section with a form feed and a comment like the following:

    // Constants and fields.
    // -------------------------------------------------------------------------
  

• Keep lines under 80 columns wide.

• All top-level class and interface declarations should begin at column zero, and the opening brace should be on the next line, in column zero.

• Method declarations and member class declarations should begin at the next level of indentation. That is, a method declaration for the top-level class would be indented two spaces, and that method's opening and closing braces are on their own lines indented two spaces.

• List modifiers in this order: access modifier, static or abstract, final, synchronized, then anything else.

• Put a space between a keyword or method name and the opening parentesis, but not if the method takes no arguments:

    if (condition)
      ...
  
    method (parameters);
    method();
  

• Indent the braces for control structures like this:

    for (int i = 0; i < limit; i++)
      {
        statements;
      }
  

• Omit the braces for control structures if there is only a single statement in the body:

    while (condition)
      statement;
  

• If a parameter list or list of conditionals will not fit on a single line, break the list and indent under the opening parenthesis:

    method(parameterOne, parameterTwo + 42, (Cast) parameterThree,
           parameterFour, parameterFive);
  
    if (conditionOne < limitOne && conditionTwo != limitTwo
        && conditionThree)
  

  If the opening parenthesis starts at column 40 or greater, however, break the line and indent two spaes.

• If the ``throws'' clause of a method, if any, will not fit on the same line as the method declaration, break the line before the throws keyword and indent two spaces:

    someLongMethodName(SomeClass someParameter, AnotherClass anotherParameter)
      throws SomeException
    {
    }
  

  If the list of exceptions will not fit on a single line, break the line and indent past the throws:

    someLongMethodName(SomeClass someParameter, AnotherClass anotherParameter)
      throws SomeException, AnotherException, AThirdException,
             AFourthException
    {
    }
  

• Chain your exceptions! It greatly aids debugging if you can get a complete stack trace:

    someExceptionMethod() throws SomeException
    {
      try
        {
          someOtherExceptionMethod();
        }
      catch (SomeOtherException soe)
        {
          SomeException se = new SomeExceptino (soe.getMessage());
  	se.initCause (soe);
  	throw se;
        }
    }
  

• Method parameters that are not changed should be marked final, as should any member fields in an immutable class.

The following is a basic example of how to format your source code:

/* One line to describe the class.
   Copyright (C) 2004  Free Software Foundation, Inc.

This file is part of GNU Crypto.

GNU Crypto 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, or (at your option) any
later version.

GNU Crypto is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; see the file COPYING.  If not, write to the

   Free Software Foundation Inc.,
   59 Temple Place - Suite 330,
   Boston, MA 02111-1307
   USA

Linking this library statically or dynamically with other modules is
making a combined work based on this library.  Thus, the terms and
conditions of the GNU General Public License cover the whole
combination.

As a special exception, the copyright holders of this library give you
permission to link this library with independent modules to produce an
executable, regardless of the license terms of these independent
modules, and to copy and distribute the resulting executable under
terms of your choice, provided that you also meet, for each linked
independent module, the terms and conditions of the license of that
module.  An independent module is a module which is not derived from
or based on this library.  If you modify this library, you may extend
this exception to your version of the library, but you are not
obligated to do so.  If you do not wish to do so, delete this
exception statement from your version.  */


package ...;

import ...;

public class ClassName extends SuperClass implements Interface
{

  // Constants and fields.
  // -------------------------------------------------------------------------

  public static final Object CONSTANT;

  private final Object field;

^L// Constructors.
  // -------------------------------------------------------------------------

  public ClassName(final Object field)
  {
    this.field = field;
  }

  public ClassName()
  {
    this(CONSTANT);
  }

^L// Class methods.
  // -------------------------------------------------------------------------

  public static Object classMethod() throws SomeException
  {
    ...;
  }

^L// Instance methods.
  // -------------------------------------------------------------------------

  public Object getField()
  {
    return field;
  }
}