Formatting

The Purpose of Formatting

The coding style and readability set precedents that continue to affect maintainability and extensibility long after the original code has been changed beyond recognition.

Vertical Formatting

How big should a source file be? Small files are usually easier to understand than large files are.

The Newspaper Metaphor

We would like a source file to be like a newspaper article. The name should be simple but explanatory. Detail should increase as we move downward.

Vertical Openness Between Concepts

Each blank line is a visual cue that identifies a new and separate concept

package fitnesse.wikitext.widgets;
import java.util.regex.*;

public class BoldWidget extends ParentWidget {
  public static final String REGEXP = "'''.+?'''";
  private static final Pattern pattern = Pattern.compile("'''(.+?)'''",
    Pattern.MULTILINE + Pattern.DOTALL
  );

  public BoldWidget(ParentWidget parent, String text) throws Exception {
    super(parent);
    Matcher match = pattern.matcher(text);
    match.find();
    addChildWidgets(match.group(1));
  }

  public String render() throws Exception {
    StringBuffer html = new StringBuffer("<b>");
    html.append(childHtml()).append("</b>");
    return html.toString();
  }
}

Vertical Density

Vertical density implies close association. So lines of code that are tightly related should appear vertically dense.

Vertical Distance

Concepts that are closely related should be kept vertically close to each other to avoid forcing our readers to hop around through our source files and classes.

• Variable declarations: Variables should be declared as close to their usage as possible.
• Instance variables: should all be declared in one well-known place (e.g. at the top of the class, at then end of the class).
• Dependent functions: If one function calls another, they should be vertically close, and the caller should be above the callee, if at all possible.

Vertical Ordering

In general we want function call dependencies to point in the downward direction. That is, a function that is called should be below a function that does the calling.

Also, we expect the most important concepts to come first.

Horizontal Formatting

Programmers clearly prefer short lines (80 to 120 characters).

Horizontal Openness and Density

We use horizontal white space to associate things that are strongly related and disassociate things that are more weakly related.

Horizontal Alignment

Using horizontal alignment to accentuate certain structures is not useful:

public class FitNesseExpediter implements ResponseSender
{
  private   Socket            socket;
  private   InputStream       input;
  private   OutputStream      output;
  private   Request           request;
  private   Response          response;
  private   FitNesseContext   context;
  protected long              requestParsingTimeLimit;
  private   long              requestProgress;
  private   long              requestParsingDeadline;
  private   boolean           hasError;

Indentantion

A source file is a hierarchy rather like an outline. Each level of this hierarchy is a scope into which names can be declared and in which declarations and executable statements are interpreted. And each level of hierarchy is differentiated using indentantion. This allows readers to quickly hop over scopes.

Breaking indentation: It is sometimes tempting to break the indentation rule for short if statements, short while loops, or short functions. However it is preferable to expand and indent those scopes.

Team Rules

A team of developers should agree upon a single formatting style.