cleaning-code

Clean Code

Evidence base: Robert C. Martin, Clean Code: A Handbook of Agile Software Craftsmanship (2008) and Clean Architecture (2017); Martin Fowler, Refactoring: Improving the Design of Existing Code (1999); cleancoder.com. Chapter references cite Clean Code unless noted otherwise.

Load-bearing rule — maximum simplicity

Boy Scout Rule: leave every piece of code cleaner than you found it (Clean Code, Preface). Simple is the default; complexity earns its place against a specific constraint.

Functions (Ch 3)

• Small — "first rule: functions must be compact; second rule: functions must be even more compact." Aim 5–10 lines; 20 is already large; blocks inside if/else/while should be one line, ideally a function call (Ch 3 "Small!" + "Blocks and Indenting", p. 34–35)
• One thing — operational test: try to extract another function whose name isn't a paraphrase of the body. If the extraction is meaningful, the original did more than one thing (Ch 3 "Do One Thing" / "One Level of Abstraction", p. 36)
• 0–2 arguments ideal; 3 requires justification; more → group into an object ("Function Arguments")
• No boolean flags — a flag argument hides two functions in one; split them ("Flag Arguments")
• No side effects — what the name doesn't promise, the body doesn't do ("Side Effects")
• Descriptive name — a long, clear verb beats a short, vague one ("Use Descriptive Names")
• Return the transformed value; don't mutate the argument — Buffer transform(Buffer in) beats void transform(Buffer out) (Ch 3 "Standard Unary Forms", p. 66)
• Separate command from query — a method either does or answers, never both (Ch 3 "Command Query Separation", p. 45; Fowler Ch 10 "Separate Query from Modifier", p. 282)
• Treat parameters as final; if you need to change the value, copy into a local (Fowler Ch 6 "Remove Assignments to Parameters", p. 144)

Names (Ch 2)

• Reveal intent — the name answers why this variable exists and how it is used
• Pronounceable — generationTimestamp, not genymdhms
• No type encodings — name, not strName / m_name / userObj
• Named constants — DAYS_IN_WEEK beats the literal 7 (magic numbers have no search anchor)
• Searchable — the identifier is distinctive enough that grep finds exactly the intended use
• Don't disinform — never reuse l/O (look like 1/0); never name a thing accountList unless it is a List (Ch 2 "Avoid Disinformation", p. 19–20)
• Pick one word per concept — fetch OR retrieve OR get, not all three (Ch 2 "Pick One Word per Concept", p. 26)
• Class names are nouns; method names are verbs — a Manager / Processor class name hints at an SRP violation (Ch 2 "Class Names" / "Method Names", p. 25)