| name | fable-code |
| description | What Fable-quality code looks like and how to produce it: altitude, naming, comments, idiom-matching, error handling, tests, dependencies. Load before writing or changing any code that another human or agent will later read — which is all code. Complements fable-method (process) with the artifact-level standard. |
Fable code
The unit of code quality is the diff, and the metric is: can a reviewer
verify it by reading it? Everything below serves that.
Read before you write. Open the surrounding code first and match its
idiom — naming style, comment density, error style, file layout. Your
personal style is worth less than the codebase's consistency. A diff that
introduces a second way of doing something the repo already does one way
is a defect even when it works.
Write at the altitude of the problem. No abstraction for single-use
code. No configurability nobody asked for. No handling of states that
cannot occur. The structure of the solution should be readable off the
structure of the problem; every layer you add that isn't in the problem
is a layer every future reader must see through.
Duplicate twice, abstract on the third — and only for same-reason
change. Two copies that will change for the same reason are one
abstraction waiting; two copies that merely look alike are a trap, and
unifying them couples things that need to diverge. Coincidental
similarity is not duplication.
Comments state what the code cannot. A comment earns its line only by
carrying a constraint invisible in the code: "must run before X because
Y," "this API silently truncates past 4096," "deliberately O(n²), n≤20."
Never narration ("increment the counter"), never provenance ("added to
fix bug"), never self-justification aimed at a reviewer. If you're
explaining what the next line does, rename things until you don't have to.
Name for the caller, not the implementation. A name should tell the
call site what it gets, not how the inside works — resolveOwner, not
walkParentChainAndCheckCache. When you can't name something cleanly,
that's the design telling you the boundary is in the wrong place; move
the boundary, don't reach for a vaguer word.
Fail loudly at boundaries, trust the interior. Validate at the edges —
user input, network, file, cross-service — and fail with messages that
name the actual problem and value. Inside your own call graph, don't
re-check what the type system or the caller's contract already
guarantees; defensive re-validation everywhere is noise that hides the
real checks.
Delete what your change orphans; flag what it doesn't. Your diff owns
its own garbage — dead branches, unused imports, obsolete comments your
change created. Pre-existing dead code gets flagged in the report, never
deleted unasked: reviewability of THIS change beats tidiness of the repo.
Tests pin contracts, not internals. Write the test that would catch
the regression you'd actually be sad about, phrased against observable
behavior — inputs and outputs, not private call order. A test coupled to
internals fails on every refactor and trains people to update tests
without reading them, which is worse than no test. And a test you never
saw red verifies nothing: break the code once, watch it fail, restore.
Every dependency is a marriage. You inherit its bugs, its release
cadence, its security surface, its transitive tree. Prefer thirty lines
of your own boring code to a small package; take a dependency when it
owns a genuinely hard domain (crypto, parsing, timezones) — never to
save an afternoon.
Leave the diff reviewable. One concern per commit; a moved file and a
changed file are two commits; formatting churn never shares a diff with
logic. If you notice the diff needs a narrator, restructure it until it
doesn't — the diff is the deliverable, the code is just what it produces.
