readable-code

Readable Code

The local-clarity sibling of code-structure. code-structure carves the units and their contracts; this skill shapes how a single body reads to a human once those units exist. Four owners, one test:

• hygiene = DELETE what git or a library already owns -- a restating comment, dead code, a name that lies or says nothing. A rule that says delete X is hygiene's.
• readable-code = READ -- shape control flow, the naming of a set of identifiers, and the order and locality of a body so a reader follows it straight down holding as little in mind as possible.
• code-structure = SHAPE THE UNITS -- decomposition and depth, cohesion, coupling, interfaces, contracts, data invariants. Anything about where a seam falls or how big a unit should be is code-structure's (it owns the size-vs-depth resolution); this skill assumes the units are already carved and asks only whether each reads clearly.
• pythonica = Python mechanics -- a rule naming a Python construct (a comprehension, match, a context manager) is pythonica's; keep this skill language-agnostic.

Every rule below is a recognizable smell (something a reader or author can actually spot) -> the principle it violates -> a fix direction. No line or nesting-depth count gates any rule; that false precision is what these qualitative smells replace.

Control-flow shape

The physical shape should mirror the logical shape.

• Buried happy path -- SMELL: you cannot find the main story; it sits at the deepest indent behind a stack of preconditions, tangled at the same level as the error handling, its matching else far below. PRINCIPLE: the main path should run straight down the trunk at one indentation level while edge and error cases are detected, handled, and dismissed in the margin. FIX: invert each precondition into an early return or continue at the top so the primary path falls through unindented. Judge success by whether the main path became unconditional and reads straight down, not by how many levels you removed.
• Predicate you must invert in your head -- SMELL: if (!isNotReady), or a two-armed branch whose if handles the rare case while the else quietly holds the norm -- you unwind a double negative or reverse the arms just to learn which case is normal. PRINCIPLE: a positively-named predicate reads as a plain assertion, and leading with the common case tells the normal story first. This is shape, not honesty: a truthful negative flag neither lies nor is empty, so hygiene's tests pass it -- reshaping it for readable phrasing is this skill's job. FIX: name the boolean for its affirmative state (is_ready) and phrase the test positively; where a genuine two-way branch remains, order it so the common case leads.
• Cleverness the next reader must decode -- SMELL: the next reader has to hand-execute the line to know what it yields -- a nested ternary, several operations folded into one dense one-liner, arithmetic on booleans; the author-side tell is a flicker of pride in the compactness, unreliable precisely for the author who prizes it. The cleverness is the point, not a constraint the plain form was measured to fail. PRINCIPLE: code is read far more often than written, so the author's one-time cleverness is repaid as a recurring decoding cost by every later reader. FIX: write the obvious form by default; reach for the dense one only when the plain form is measured to fail a real constraint (a hot path, a memory ceiling) -- and that necessity is exactly the unrecoverable WHY that earns a comment (see hygiene, Comments/KEEP).
• A loop that hides a named operation -- SMELL: a manual accumulation loop reimplements one well-known operation -- a sum, an any/all, a max-by, a group-by -- so a reader must execute the loop mentally to recover an operation that already has a plain name. PRINCIPLE: name the operation, so the code reads as what it computes ("these are the eligible ones") instead of how it accumulates. FIX: replace the loop with the named operation (a map/filter/reduce, a library call) or an intention-named helper. Discriminator (this is the positive complement to the cleverness rule, not its contradiction): this applies only when the loop is one nameable operation; several operations folded into one dense expression stay in the plain form.