Code Comment
Prose inside source code, useful only when it records a constraint the code cannot state.
A code comment is prose embedded in source. Whether a given comment earns its place has a sharp test, and it is not "does this explain the code":
A comment worth keeping answers what breaks if you rewrite this? A comment worth cutting answers why did this change?
The second kind narrates the conversation that produced the line — "the port welded these together", "regression: previously returned null", "added for issue 412". It makes sense only to someone who read the change that introduced it, and it is exactly the information the version-control history already holds and holds better. See Provenance.
The first kind records a constraint that is invisible from the code and will be reintroduced as a bug if removed: an ordering requirement, a platform quirk, a reason the obvious simplification does not work. That is the same category as Chesterton's Fence — a comment is the cheapest way to stop a future reader from tearing the fence down.
Two mechanical hazards. A comment stating a causal mechanism nobody verified is worse than none, because it inherits the credibility of the source file it lives in — see Plausible Mechanism. And a documentation block binds to whatever declaration follows it, so inserting a new declaration above one silently transfers the docs to the wrong thing.
See also5
Hand-picked in the note itself — the neighbours worth reading next.
Documentation Rot
Documentation that has drifted from the system it describes, and is now worse than none.
Method20 connections
Naming
Choosing identifiers so the code states its own meaning without commentary.
Method21 connections
Code Review
A second person reading a change before it lands, and the practices that make it worth the time.
Version Control & Delivery15 connections
Chesterton's Fence
Do not remove something whose purpose you cannot explain.
Method11 connections
Plain Language
Writing so that the intended reader can find, understand, and use the information the first time.
Meaning & Society14 connections
Related2
Nearby in the graph rather than deliberately chosen. Looser, sometimes surprising.
Linked from9
Notes elsewhere in the wiki that reach for this one.
- Chesterton's FenceMethod
Do not remove something whose purpose you cannot explain.
- Code ReviewVersion Control & Delivery
A second person reading a change before it lands, and the practices that make it worth the time.
- Documentation RotMethod
Documentation that has drifted from the system it describes, and is now worse than none.
- Linguistic RelativityMeaning & Society
The hypothesis that language shapes thought, and the evidence that has narrowed it considerably.
- NamingMethod
Choosing identifiers so the code states its own meaning without commentary.
- Plain LanguageMeaning & Society
Writing so that the intended reader can find, understand, and use the information the first time.
- Plausible MechanismMethod
A causal explanation that was inferred rather than tested, and reads as more rigorous for being specific.
- ProvenanceMethod
The recorded origin of a change or a claim — who made it, when, and on what evidence.
- Technical DebtMethod
The future cost of a present shortcut, metaphorically accruing interest.