Code readability

Code is read at the point of use, by someone who does not have the author's head. A value, name, or shape that needs the author's memory to decode is a readability bug, even when it runs correctly.

Name it, or document it where it is used. Prefer naming. A named constant explains itself on every use and can only change in one place. A comment is the fallback for code that cannot hold a name (a config table, a protocol layout), and it must give the unit and the reason, not restate the literal.

Balanced, not strict. This skill flags meaning a reader cannot recover from context. It does not flag 0, 1, -1, a literal already labelled by the property or argument it sits in ({ timeoutMs: 5000 }), test data, or math whose meaning the formula itself carries (width / 2 for a centre). Chasing those teaches people to ignore the rule.

Source checks and dates: SOURCES.md.

Procedure

1. Read the change for a reader who arrives cold. Mark every place you had to scroll, guess, or already know something to understand it.
2. Read the resource for that smell in the table below.
3. Fix by preference, in order: rename, extract a named constant or helper, restructure (guard clause, lookup table), then — only if none of those fit — a unit-and-why comment at the use site.
4. Do not rename or restructure unrelated code in the same change. Readability fixes ride along only where the change already touches.
5. If the project has linting, run it. Report findings as Must fix / Should fix / Leave, with the rule name. Never report a smell you did not actually see in the code.

a literal a reader can't decode ──> magic-numbers.md, magic-strings.md
a name that hides unit or meaning ──> naming.md
a function you must hold in your head ──> functions.md, nesting-and-conditionals.md
a comment that lies, repeats, or apologises ──> comments-and-dead-code.md
want a machine to catch it ──> linting.md

Where to read

The smells that cost the most time

Review checklist

• No bare literal carries time, retries, thresholds, limits, money, rates, or sizes without a name or a unit-and-why note at the use site
• Named constants are named for meaning and unit (SESSION_TIMEOUT_MS), not for their value (TIMEOUT_180000)
• 0, 1, -1, labelled properties, and self-evident math were left alone
• Strings compared in logic are named constants, enums, or union members — never retyped literals
• No call passes bare booleans whose meaning is invisible at the call site
• Names carry their unit and do not lie about type, side effects, or contents
• Each function does one thing at one level of abstraction; length and nesting read as smell, not law
• Conditions read in the positive where they can; no nested ternaries in prose-like code
• Every comment adds why, a constraint, or a warning — none restate the code, none are stale
• No commented-out code, no unreachable branches, no TODO without an owner or issue