5.- Format

Overview

Chapter 5 establishes that code formatting is about communication – a developer’s first professional obligation. The rules chosen today affect readability and maintainability long after individual lines have changed. The chapter provides concrete guidelines for vertical and horizontal organisation, and closes with the principle that teams must agree on a single formatting standard.

The Purpose of Formatting

Code formatting is about communication, and communication is a professional developer’s first priority. Readable, consistent style improves maintainability and extensibility long after individual lines of code have changed.

Vertical Formatting

File Length

Aim for files around 200 lines, with an upper limit of about 500. Smaller files are usually easier to understand than large ones.

The Newspaper Metaphor

• The filename should be simple yet descriptive.
• The top of the file should expose the highest-level concepts; detail should increase as you move downward, ending with low-level utilities.

Vertical Openness Between Concepts

Separate distinct thoughts with blank lines. Most code is read left-to-right, top-to-bottom; whitespace helps readers see where one idea ends and the next begins.

Vertical Density

Lines that are tightly related should sit close together.

public class ReporterConfig {

  private String m_className;
  private List<Property> m_properties = new ArrayList<>();

  public void addProperty(Property property) {
    m_properties.add(property);
  }
}

Vertical Distance

Closely related concepts belong vertically close – often in the same file – unless you have a compelling reason to separate them. This reduces “file hopping”.

• Variable declarations – place them near their first use.
• Loop variables – declare them inside the loop.
• Instance variables – declare them at the top of the class.
• Dependent functions – if f() calls g(), place f() above g() when possible.
• Conceptual affinity – functions that perform similar work or operate on the same data belong together.

Vertical Ordering

Strive for a top-down dependency flow: high-level functions first, low-level details last.

Horizontal Openness and Density

Use horizontal whitespace to associate strongly related elements and to separate weakly related ones.

• No space between a method name and its ( – they are inseparable.
• Space around = highlights the left side vs. right side of an assignment.
• Space after commas separates arguments.

Operator Precedence with Whitespace

Multiplication has higher precedence, so factors appear without spaces; addition/subtraction have lower precedence, so terms are separated by spaces:

return (-b + Math.sqrt(det)) / (2 * a);

Horizontal Alignment

Avoid large columns of aligned assignments; excessively long aligned lists usually signal that the list itself is the problem.

Indentation

Source files form a hierarchy (file -> class -> method -> block). Indent code one level deeper for each nested scope. Good indentation visually communicates scope and structure; broken indentation obscures it.

Team Rules

A team of developers should agree on a single formatting standard and every member must comply with it. Good software is composed of documents that read consistently. Readers must be able to trust that formatting gestures in one source file mean the same in others.

Use an automated formatter to enforce the agreed standard and remove formatting debates from code reviews.

Key Rules / Quick Reference

• Files should be around 200 lines; 500 is the upper limit.
• Top of file = high-level concepts; bottom = low-level details (Newspaper Metaphor).
• Use blank lines to separate concepts; keep related lines dense.
• Declare variables close to their first use; instance variables at the top of the class.
• Caller functions above callee functions – top-down flow.
• No space between function name and (; space around assignment operators.
• One indent level per nested scope.
• Teams agree on one standard and automate enforcement.

Summary

Formatting is not a personal preference – it is a professional responsibility. The goal is code that communicates clearly to every reader. Apply vertical and horizontal rules consistently, automate the standard with a formatter, and ensure the entire team speaks the same formatting language.