code-readability

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