Clean Code — key concepts
Martin's central claim is that code is read far more often than it is written, so the primary measure of quality is how easily another person, or the same developer months later, can understand it. He translates that into concrete discipline: meaningful names, functions that do one thing at one level of abstraction, comments treated as a last resort rather than a first response, and the Boy Scout Rule of leaving every file a little cleaner than you found it. Recurring code smells, and principles like the Single Responsibility Principle, give the discipline a shared vocabulary.
Meaningful Names
Martin argues a name should reveal intent well enough that a reader never needs a comment to explain it: a variable, function, or class name should say why it exists, what it does, and how it's used. He treats vague names, disinformation, and needless abbreviation as small debts that compound, since code is read far more often than it's written.
Functions Should Do One Thing
Martin's rule for functions is severe: they should be small, then smaller still, and each one should do exactly one thing, do it well, and do it only. He extends this into the Stepdown Rule, where a well-written program reads top to bottom like a narrative, each function followed by the next one down in its level of abstraction.
Comments Are a Failure of Expression
Martin treats most comments as an apology: a sign that the code itself failed to explain what it does, so a comment had to compensate. Comments rot because they aren't maintained the way code is, and a misleading comment is worse than no comment at all; his preference is almost always to rewrite the code until it no longer needs one.
The Boy Scout Rule
Borrowed from scouting, Martin's rule is to leave the campground cleaner than you found it: every time a developer touches a file, they should make some small improvement, a better name, a shorter function, one less duplication, beyond whatever task brought them there. Applied consistently across a team, this continuous small cleanup is what keeps a codebase from decaying.
Prefer Exceptions to Error Codes
Martin argues that returning error codes forces the calling code to check a condition immediately after every call, cluttering the logic with housekeeping and tempting callers to forget the check entirely. Throwing an exception instead separates error handling from the main algorithm, since the try/catch block can live in one place while the happy-path logic stays uncluttered.
Answer these before you check.
These are the kind of open questions Recall asks in a real review session — no multiple choice, no re-reading the highlight first. Try answering out loud or on paper, then open the reveal to self-grade.
01Why does Martin treat most comments as a failure rather than a virtue, and what does he recommend instead of writing one?
Martin's view is that a comment is usually an apology for code that couldn't express itself: the programmer knew the logic was confusing but fixed the confusion with an explanation rather than a rewrite. Comments are also a maintenance liability, because nothing forces them to change when the code around them does, so a stale comment can actively mislead a reader who trusts it over the code. His preferred fix is almost always to rewrite the code so its intent is obvious: extract a function and give it a name that states what the block below used to need a comment to explain.
02What is the Boy Scout Rule, and how does Martin argue it keeps a large codebase from decaying over time?
The Boy Scout Rule says to leave the campground cleaner than you found it: whenever a developer is already in a file for some other reason, they should make one small improvement beyond their assigned task, renaming a confusing variable, breaking up an oversized function, removing a bit of duplication. No single change fixes the codebase, but Martin argues that applied consistently by everyone on a team, these small acts of care outpace the small acts of neglect that would otherwise accumulate, so overall quality trends up instead of slowly rotting.
03According to Martin, why should a function do only one thing, and how can a developer tell whether it does?
Martin argues that a function mixing multiple levels of work, say, validating input, running business logic, and formatting output, is doing more than one thing, which makes it harder to name honestly, harder to test in isolation, and harder to reuse. His test is whether you can extract another function from it with a name that isn't just a restatement of its implementation; if you can, the original was doing more than one thing. Small, single-purpose functions also let a program read top to bottom like a narrative, which he calls the Stepdown Rule.
This is a one-time snapshot. Recall keeps testing you on it.
Import your own highlights from Clean Code (or any book) and Recall generates fresh open questions, grades your free-text answers, and schedules the next review with spaced repetition — so the concepts above don't fade in a month.