Clean Code: Chapter 5 Notes

• Tightly related lines should appear vertically dense.
• Avoid useless comments that interrupt association.
• Example (bad):

public class ReporterConfig {
/**
* The class name of the reporter listener
*/
private String m_className;

• Example (better):

public class ReporterConfig {
private String m_className;
private List<Property> m_properties = new ArrayList<>();

• Related concepts should be kept close together to reduce scrolling and searching.
• Local variables → as close to use as possible, usually at top of function.
• Control variables → declared inside loop headers.
• Instance variables → declared at the top of class (common Java convention).

for (Test each : tests) {
    count += each.countTestCases();
}

• Dependent functions: caller above callee for natural top-down reading.

public Response makeResponse(...) {
    String pageName = getPageNameOrDefault(request, "FrontPage");
    loadPage(pageName, context);
    return makePageResponse(context);
}

private String getPageNameOrDefault(Request request, String defaultPageName) { ... }

• Group functions with similar naming or shared purpose.
• Example (JUnit assert methods):

static public void assertTrue(String message, boolean condition) { ... }
static public void assertTrue(boolean condition) { ... }
static public void assertFalse(String message, boolean condition) { ... }
static public void assertFalse(boolean condition) { ... }

• Organise code top down:
  • High-level concepts first (main logic).
  • Lower-level details later.
• Readers can skim like a newspaper: important first, details last.
• Contrast: C/C++ require declarations before use, Java does not.

• Use vertical openness to separate concepts.
• Use vertical density to group related ones.
• Keep related variables, methods, and concepts close together.
• Order code top down for natural readability.

Use spaces to separate low-precedence operators (e.g., +, -, =) and improve readability.

Do not put spaces between function names and parentheses, they are closely related.

Example (Quadratic formula formatting):

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

Separate arguments with spaces after commas to show distinct parameters.

Avoid aligning variable declarations or assignments in columns, it draws the eye to the wrong place.

Long aligned lists usually mean the class is too large and should be split.

Example (preferred unaligned):

// Prefer this:
private Socket socket;
private InputStream input;
private OutputStream output;

//instead of:
private Socket       socket;
private InputStream  input;
private OutputStream output;

Indent according to scope hierarchy:

Classes → no indent

Methods → 1 level

Method bodies → 2 levels

Inner blocks → +1 for each nesting

Indentation makes scopes visually obvious; without it, code is hard to scan.

Avoid collapsing scopes onto one line, always use braces and proper indenting.

Avoid dummy bodies in loops (e.g., empty while or for loops).

If unavoidable, place semicolon on its own indented line to make it visible.

while (dis.read(buf, 0, size) != -1)
    ;