<<Clean Code>> Quotes: 5. Formatting

you should take care that your code is nicely formatted.

The Purpose of Formatting

Code formatting is important.

Code formatting is about communication, and communication is the professional developer’s first order of business.

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

Vertical Formatting

It appears to be possible to build significant systems out of files that are typically 200 lines long, with an upper limit of 500.

The Newspaper Metaphor

We would like a source file to be like a newspaper article. The name should be simple but explanatory. The name, by itself, should be sufficient to tell us whether we are in the right module or not. The topmost parts of the source file should provide the high-level concepts and algorithms. Detail should increase as we move downward, until at the end we find the lowest level functions and details in the source file.

Vertical Openness Between Concepts

Each line represents an expression or a clause, and each group of lines represents a complete thought. Those thoughts should be separated from each other with blank lines.

Vertical Density

If openness separates concepts, then 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. Clearly this rule doesn’t work for concepts that belong in separate files. But then closely related concepts should not be separated into different files, unless you have a very good reason.

For those concepts that are so closely related that they belong in the same source file, their vertical separation should be a measure of how important each is to the understandability of the other.

Variable Declarations. Variables should be declared as close to their usage as possible. Because our functions are very short, local variables should appear at the top of each function. … Control variables for loops should usually be declared within the loop statement.

Instance variables, on the other hand, should be declared at the top of the class. This should not increase the vertical distance of these variables, because in a well-designed class, they are used by many, if not all, of the methods 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. This gives the program a natural flow.

Conceptual Affinity. Certain bits of code want to be near other bits. They have a certain conceptual affinity. The stronger that affinity, the less vertical distance there should be between them. … this affinity might be based on a direct dependence, such as one function calling another, or a function using a variable. … Affinity might be caused because a group of functions perform a similar operation.

Vertical Ordering

In general we want function call dependencies to point in the downward direction.

As in newspaper articles, we expect the most important concepts to come first, and we expect them to be expressed with the least amount of polluting detail. We expect the low-level details to come last. This allows us to skim source files, getting the gist from the first few functions, without having to immerse ourselves in the details.

Horizontal Formatting

The old Hollerith limit of 80 is a bit arbitrary, and I’m not opposed to lines edging out to 100 or even 120. But beyond that is probably just careless.

Horizontal Openness and Density

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

private void measureLine(String line) {
  lineCount++;
  int lineSize = line.length();
  totalChars += lineSize();
  lineWidthHistogram.addLine(lineSize, lineCount);
  recordWidestLine(lineSize);
}

On the other hand, I didn’t put spaces between the function names and the opening parenthesis. This is because the function and its arguments are closely related. … I separate arguments within the function call parenthesis to accentuate the comma and show that the arguments are separate.

public class Quadratic {
  public static double root1(double a, double b, double c) {
    double determinant = determinant(a, b, c);
    return (-b + Math.sqrt(determinant) / (2*a);
  }
  private static double determinant(double a, double b, double c) {
    return b*b - 4*a*c;
  }
}

The factors have no white space between them because them are high precedence. The terms are separated by white space because addition and subtraction are lower precedence.

Horizontal Alignment

private   Long            requestParsingTimeLimit;
protected Request         request;
private   FitNesseContent context;
this.context =            context;
input =                   s.getInputStream()
requestParsingTimeLimit = 900;

I have found, however, that this kind of alignment is not useful. The alignment seems to emphasize the wrong things and leads my eye away from the true intent.

Indentation

A source file is a hierarchy rather link and outline.

Each level of this hierarchy is a scope into which names can be declared and in which declarations and executable statements are interpreted.

To make this hierarchy of scopes visible, we indent the lines of source code in proportion to their position in the hierarchy.

BreakingIndentation. It is sometimes tempting to break the indentation rule for short if statements, short while loops, or short functions. Whenever I have succumbed to this temptation, I have almost always gone back and put the indentation back in.

Dummy Scopes

I make sure that the dummy body is properly indented and surrounded by braces.

Team Rules

A team of developers should agree upon a single formatting style, and then every member of that team should use that style.