code-commentslisted

# code-comments A comment is written for one reader: whoever is about to change the line it sits on. That reader can see what the line does. What they cannot see is the constraint that made it the right line, and a comment that does not carry one is a line of code with no code in it Everything below follows from the reader. The caller has `--help`, the person choosing the project has the readme, and whoever needs the arrangement explained has the maintainer documents; none of them is reading this line [`check-comments.sh`](check-comments.sh) beside this file decides the machine-decidable half: it reads comments out of each file's syntax tree, so a `#` inside a string is never one, and proves every rule able to fail on a planted copy before it reads anything real. `check-comments.sh --help` is the reference for what it checks and how a line is excused ## What a comment carries - **The reason, not the restatement.** `# enable bluetooth` above `hardware.bluetooth.enable = true` says nothing the line has not said. What earns the place is a constraint, an upstream defect, an order that matters, a measured cost - **A reason that outlives the moment.** Not "removed on 2026-07-22" but "removed from nixpkgs because it needed GTK2". The danger is not the date but the dependency: a comment anchored to a moment is true only while something it cannot observe stays the same, and it goes on reading as true after it stops being so. Version pins live in the lock file - **Nobody's voice.*