clean-code

Clean Code craftsmanship (Uncle Bob)

Guidance for writing and reviewing code to Robert C. Martin's standards. Apply these as working discipline, not as dogma — the goal is code that reads like well-written prose and is cheap to change. When reviewing, cite the specific principle and show the smallest fix.

The prime directive

Leave the code cleaner than you found it. — The Boy Scout Rule

Make it work, make it right, make it clean — in that order, but never skip the last step. Prefer many small, safe, verifiable changes over one large rewrite.

Meaningful names

• Intention-revealing: the name answers why it exists, what it does, how it's used. elapsedTimeInDays beats d.
• Avoid disinformation and noise words (Manager, Data, Info, theList).
• Make meaningful distinctions — no a1, a2; no ProductData vs ProductInfo.
• Pronounceable and searchable. Class = noun phrase, method = verb phrase.
• One word per concept (fetch/get/retrieve — pick one). No cute puns.

Functions

• Small. Then smaller. Ideally a handful of lines; rarely more than ~20.
• Do one thing, at one level of abstraction. If you can extract another function with a non-restating name, it was doing more than one thing.
• Few arguments. 0–2 ideal, 3 needs justification, 4+ almost never. No flag arguments — split into two functions. Wrap related args into an object.
• No side effects the name doesn't advertise. Command/Query Separation: a function either does something or answers something, never both.
• Don't Repeat Yourself. Duplication is the root of most maintenance cost.
• Prefer exceptions to returned error codes; extract try/catch bodies into their own functions so error handling is one thing.

Comments

• A comment is a failure to express intent in code — first try to refactor so the comment is unnecessary (better name, extracted function, explaining var).
• Good comments: legal headers, explanation of intent/consequence, warnings, TODO, public-API docs. Bad: redundant, misleading, commented-out code (delete it — version control remembers), journal/attribution noise.