Answer prose round 1: DRY's guide names what it breaks, yields to copies that cannot disagree, and the rejection rule names the surface exception

This commit is contained in:
2026-10-07 23:16:07 +02:00
parent fe916873f6
commit 95fd2588c0
+2 -2
View File
@@ -61,9 +61,9 @@
- An import sorts on its first binding, not its path, so moving or renaming a module reorders nothing. Where lines already group by kind — type imports, host packages — the key sorts within each group.
* Keep It Simple, Stupid (KISS): keep solutions simple, so a reader new to the project understands each part on one read.
- Keep a size or complexity limit only while the comprehension panel's readers (`~/.claude/skills/comprehension-panel/`) find the code it flags hard.
* Don't Repeat Yourself (DRY) is a guide, not an absolute rule: one authoritative home per piece of knowledge, one obvious way per need. Before applying it, ask whether the code would be easier to understand, easier to reason about, or easier to maintain if it were broken; if so, break it. A surface people write — a template, data, an API — may accept a second spelling where that makes it easier to use.
* Don't Repeat Yourself (DRY) is a guide, not an absolute rule. It aims at one authoritative home per piece of knowledge, one obvious way per need. Before applying it, ask whether the code would be easier to understand, easier to reason about, or easier to maintain if DRY were broken; if so, break it, so long as the copies cannot disagree (below). A surface people write — a template, data, an API — may accept a second spelling where that makes it easier to use.
- A value, rule, definition or concept lives in one place, and everywhere else derives it from there or points at it. A copy that can drift is a second spelling: derive it from its owner, or, for config a human writes, reject it where it is read and name the owner.
- Before adding a way to do something, find the existing one and use it. The same goes for tests: extend an existing test with an assertion before writing a new one. Where two spellings serve the same caller for the same need, keep one and reject the other as early as possible — at load, parse or compile — with an error naming the one to use: `token {p} renders a level that {p.first} reads a path into; name the fields you want instead`.
- Before adding a way to do something, find the existing one and use it. The same goes for tests: extend an existing test with an assertion before writing a new one. Where two spellings serve the same caller for the same need, and the second makes no surface people write easier to use, keep one and reject the other as early as possible — at load, parse or compile — with an error naming the one to use: `token {p} renders a level that {p.first} reads a path into; name the fields you want instead`.
- Different needs may have different ways. A public API may offer a convenience beside the general form — a one-line call for the common case over the primitive for the rest — where each serves a caller or scenario its docs name, and the convenience is built from the primitive. Code that looks alike but encodes different knowledge is not a second spelling: merging it is the wrong abstraction.
- Two spellings that can disagree are a correctness bug, whatever the reason for having both: derive one from the other, or reject the combination.
* All critical flows should have good traces, from where something was initiated until it completed.