About the Why Layer
Code records what it does. It almost never records why. Six months on, a strange-looking conditional is indistinguishable from a mistake, and the person who could explain it has left. Someone "cleans it up" and reopens the incident it was written to prevent.
The Why Layer attaches reasoning to specific lines: the business rule that forced the odd branch, the upstream bug the workaround exists for, the profiling result behind the ugly optimisation. The annotations live alongside the code rather than inside it, so they do not clutter the source and they survive reformatting.
When you'd use it
- Documenting why a workaround exists, with the upstream issue link, so nobody removes it.
- Recording the business rule behind a magic number or an unusual condition.
- Explaining a non-obvious optimisation and what the profiling actually showed.
- Capturing security-relevant reasoning — why validation happens at this specific boundary.
- Handing over a system: annotating the parts that surprise people before you leave the team.
The six annotation types
Categories exist so you can filter to the ones that matter for the task at hand.
- Business Rule — a requirement from outside the code. Tax rules, contractual thresholds, regulatory constraints.
- Bug Workaround — code that exists because something else is broken. The most valuable to annotate, because it is the most likely to be deleted by someone who does not know.
- Performance — a decision made for measured speed reasons. Record the measurement, not the intuition.
- Security — why a check is here, why input is treated as hostile, why this boundary is the right one.
- Architecture — a structural decision and the alternatives that were rejected.
- Tech Debt — a known compromise, ideally with the condition that should trigger fixing it.
What makes an annotation worth writing
A comment that restates the code adds nothing. A good why-annotation contains something not derivable from reading the source: an external constraint, a date, an incident number, a measurement, a decision that was made and the option that was rejected.
"Retry three times" is worthless — the code says that. "Three retries because the payment provider's p99 recovery is under two seconds and their support confirmed a fourth attempt risks duplicate charges, INC-4471" is the kind of thing that stops someone changing it to five.
Where annotations are stored
Everything is saved to your browser's local storage as you type, so a refresh does not lose work. That storage is local to one browser on one machine — it is not synced, and clearing site data erases it.
For anything you want to keep, export a .why.json file, or use Share URL, which encodes the whole project into the link itself so nothing has to be hosted. Committing the exported file next to the code is the durable option, and it gives the annotations a review history.
How this differs from comments and from git blame
Inline comments are the right tool when the explanation is short and the line is stable. They get stale, they add noise, and long ones break the flow of the code — which is why the important context often does not get written down at all.
Git blame theoretically holds this context, but in practice a reformat, a file move, or a squashed merge buries it, and most commit messages say what changed rather than why. A separate annotation layer keeps the reasoning attached to the line without putting it in the file, and exports as something you can review and diff.
Frequently asked questions
- Does this change my source files?
- No. Annotations are stored separately and referenced by line. Your code is never modified.
- What happens when the code changes?
- Annotations are anchored to line numbers, so inserting lines above an annotated line will drift it. Re-anchor after a significant edit — this is the main limitation of the approach and the reason to annotate stable code rather than code in flux.
- Can I share annotations with my team?
- Yes, two ways. Export a .why.json file, or use Share URL, which encodes the whole project into the link — nothing is uploaded, the data is in the URL itself.
- Is my code uploaded?
- No. The editor, the annotations, and the export all run in your browser, and storage is local to it.
- Which languages does the editor support?
- It uses Monaco, the editor from VS Code, so syntax highlighting covers the same broad language set. Annotations themselves are language-agnostic — they attach to line numbers.