Code Style Guide

As one of the goals of the Algorithm Study project is for the source code to be read and studied, it is important that the code be formatted in a consistent manner. This page describes the coding style used for all code committed to this project. While the coding conventions may not match your preferred style, please follow them; a submitted patch that does not follow these coding conventions may be rejected based simply on formatting grounds.

Java Style

For the most part, the Java code in the Algorithm Study project follows Sun's Java Code Conventions. The exceptions to Sun's Java code conventions are outlined below.

Indentation

  • Lines cannot exceed 100 characters
  • Indentation must be 2 spaces except when continuing an expression or declaration from a previous line; in such cases, 4 spaces should be used.
  • No Tabs. Tabs are simply not allowed. All editors can be configured to convert tabs to spaces. Make your editor do so.

Comments

  • All files must include JavaDoc comments, including unit tests
  • Multi-line comments should use /* ... */, while single line comments should use //
  • Do not use trailing comments (i.e. comments at the end of a line). To comment a line of code place the comment immediately above the line.

Declarations

  • Use one declaration per line, and use the standard Java naming conventions.
  • Class level declarations belong at the top of the class definition.

Exceptions

  • Never catch Exception or RuntimeException. Always catch the most specific type of exception thrown and handle the exception properly.

Whitespace

  • Avoid ascii art. This includes lining up method arguments that exceed a single line, indenting the right side of declaration assignment operators to make them all line up, and any other use of whitespace that does not indicate a semantic change. Using indentation to indicate that code is within a code block (and within a certain scope) is required, of course.
  • Avoid extra blank lines unless it improves readability.

Eclipse Format Configuration

An Eclipse formatter definition file that (nearly) matches this policy is included in the Algorithm Study's source repository at java/misc/Eclipse_Formatter-alg-study_Conventions.xml .

To install the formatter:

  1. Right click on project in package explorer, select "Properties"
  2. expand "Java Code Style"
  3. select "Formatter"
  4. check "Enable project specific settings"
  5. import the eclipse format configuration file