Readable Code

Three rules, one each for the three things a reader has to decode. They fire together on almost every review, which is why they live in one place.

• A name's length scales with its scope, and it must not lie. i in a three-line loop is fine; an exported name carries full meaning on its own. A get_user() that creates the user is worse than a vague name, because the reader trusts it.
• Each level of indentation is one more condition the reader holds as true. Cost compounds rather than adding up: four guard clauses cost 4, the same logic nested costs 10. Three levels is the soft ceiling.
• A comment at the same level of abstraction as the code duplicates it. Refactor until the code says it, then delete the comment. A comment that is more precise (units, bounds, invariants) or more abstract (intent, contract, rationale) carries what code cannot, and stays.

Where to look