Chapter 5 Flashcards — Formatting
flashcards clean-code formatting
What is the primary purpose of code formatting according to Clean Code?
?
Communication. Formatting is not cosmetic — it is how code conveys intent to the next reader. The original programmer moves on; the formatting must carry the message forward.
What is the recommended file size guideline in Clean Code, and what does violating it signal?
?
200–500 lines is the target. Files over 500 lines are a signal that the class is doing too many things and should be split. The FitNesse project kept most files under 200 lines.
What does a blank line communicate in a source file?
?
A visual separator between distinct concepts. A group of lines with a common purpose forms one thought; a blank line says “this thought ends here and a new one begins.” Without blank lines, the reader must parse structure manually.
What is “vertical density” and when should you use it?
?
Vertical density means placing closely related lines together without intervening blank lines or comments. Lines that form a single logical unit (e.g., a group of field declarations, a loop and its variable) should appear dense. Blank lines are reserved for conceptual boundaries, not sprinkled randomly.
What is the “vertical distance” rule for local variable declarations?
?
Declare local variables as close to their first use as possible. Separating declaration from use forces the reader to hunt up the file to understand what a variable holds. The shorter the gap, the less cognitive load.
Where should instance variables be declared in a Java or C++ class?
?
At the top of the class, grouped together. This is the well-known place every reader looks first. Scattered instance variable declarations (some at top, some mid-class) destroy the mental model.
What is the “dependent functions” ordering rule?
?
The caller should appear above the callee in the file. When function A calls function B, A comes first. This creates a top-down reading flow: high-level logic first, implementation details below — the newspaper metaphor.
Describe the “newspaper metaphor” for vertical ordering in a source file.
?
A newspaper story starts with the headline (most important), then the lead paragraph (key facts), then deeper detail. Source files should mirror this: public API (the contract) at the top, private helpers and details at the bottom. Readers can stop reading at any level and still understand the class.
What is the modern recommended line length limit, and why does it still matter on wide monitors?
?
80–120 characters. The concern is not monitor width — it’s that long lines indicate deep nesting or a function doing too much. Horizontal scrolling also breaks the reader’s vertical scanning rhythm.
What is the rule for spaces around assignment operators vs. function call parentheses?
?
Spaces around assignment operators (total = base * rate); no space between a function name and its opening parenthesis (calculate(items), not calculate (items)). The space before a paren signals “this is a keyword” (like if or while), not a function call.
How should you format a mathematical expression like b*b - 4*a*c to communicate precedence?
?
Use spaces around low-precedence operators (subtraction, addition) and no spaces around high-precedence operators (multiplication). Writing b*b - 4*a*c visually groups the tighter terms, mirroring actual operator precedence.
Why is column-aligning variable declarations or assignment operators considered a code smell?
?
The eye follows the column, not the type or semantic meaning, creating false visual grouping. It also forces unrelated changes — adding a longer name breaks the alignment everywhere. Auto-formatters remove alignment; if you feel the urge to align, it’s a sign the class has too many variables.
What does “never collapse indentation” mean, and why does it matter?
?
It means always expanding block bodies with braces and indentation, even for single-line if or while bodies (if (paid) { return; }, not if (paid) return;). The visual scope is a contract. When a second statement is added later, the brace structure prevents silent logic bugs.
What is the most important formatting principle for a team, according to Clean Code?
?
Team consistency enforced by automation. Every member uses the same style, enforced by an automated formatter (not style debates or manual PR comments). A CI gate on formatter output is the gold standard.
Name the standard automated formatting tool for each language: Java, C++, Python.
?
- Java: Google Java Format (via
spotlessMaven/Gradle plugin) or IntelliJ’s built-in formatter - C++:
clang-formatwith a.clang-formatconfig file checked into the repo - Python:
black(code style) +isort(import ordering), configured inpyproject.toml
What Python specification serves as the de facto “team rule” for formatting, and what tool enforces it?
?
PEP 8 is the community standard. black is the formatter that enforces a consistent subset of PEP 8 without configuration debates. Its “opinionated” design means teams adopt it wholesale rather than arguing about options.
What is the clang-format config file called, where does it live, and what key options does it control?
?
.clang-format, placed in the project root. Key options: BasedOnStyle (Google, LLVM, Mozilla, etc.), IndentWidth, ColumnLimit, BreakBeforeBraces, and AllowShortIfStatementsOnASingleLine (set to false for Clean Code compliance).
What is “conceptual affinity” in the context of vertical ordering?
?
Functions or declarations that are conceptually related should appear near each other in the file, even if they do not call one another. For example, static assertion helpers for the same domain object, or utility functions that all operate on the same type. Proximity signals cohesion.
A file has 850 lines. What does Clean Code say you should do and why?
?
Split it into multiple classes/files. A file over 500 lines almost always indicates multiple responsibilities in one class. Splitting improves comprehension (each piece fits on the screen), testability, and maintainability.
A junior developer asks: “Should I write if (flag) return true; on one line to save space?” What is the Clean Code answer?
?
No. Always expand the block: if (flag) { return true; }. The single-line form saves two lines but destroys the visual scope signal. When a second statement is added in the future, the missing braces create a bug risk.
What happens when instance variables are scattered throughout a class body instead of grouped at the top?
?
The reader cannot form a mental model of the class’s state without reading the entire file. They must scroll up and down to discover all the fields. Grouping at the top makes the state surface immediately visible.
Why should dependent functions be ordered caller-above-callee rather than alphabetically or randomly?
?
Alphabetical ordering destroys the logical flow. Caller-above-callee means the reader follows the code like a story: what does processOrder do? → it calls validateCart, calculateTotal, chargePayment — each defined just below. The reader descends into detail on demand.
What does Clean Code say about auto-generated code (protobuf, JAXB, ORM entities) and formatting?
?
Exempt it. Do not reformat auto-generated files — the tool that generates them owns the formatting. Reformatting makes regeneration painful. Keep generated files separate from hand-written code.
What is the risk of spaces before function-call parentheses, specifically lineWidthHistogram (line)?
?
It visually mimics a keyword (if (...), while (...), for (...)), misleading the reader into thinking it is a control-flow construct rather than a function call. Function names should be immediately adjacent to their argument list.
What is “vertical openness” and what is the anti-pattern it prevents?
?
Vertical openness is the use of blank lines to separate distinct conceptual groups (constructor, mutating methods, query methods, private helpers). The anti-pattern it prevents is “wall of code” — a file with no blank lines where every concept bleeds into the next.
Total Cards: 25
Review Time: ~18 minutes
Priority: MEDIUM
Last Updated: 2026-04-14