Make DRY a guide: break it where the code reads, reasons or maintains better, and let a surface people write accept a second spelling
This commit is contained in:
@@ -61,7 +61,7 @@
|
||||
- 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): one authoritative home per piece of knowledge, one obvious way per need.
|
||||
* 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.
|
||||
- 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`.
|
||||
- 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.
|
||||
|
||||
Reference in New Issue
Block a user