appropriate-comments-code

Appropriate Comments in Code

The Rule

A comment earns its place by carrying information the code does not, about the code as it is now, in as few lines as that takes.

Four ways to fail it, and they are equally fatal:

1. Restating the line below it.
2. Narrating how the code got here.
3. Explaining at length something true and useful — that is documentation, and documentation does not live above a function.
4. Instructing a future editor — "never", "always", "keep in step" — with nothing that fails when they ignore it. That is a promise, and a promise is enforced by a test, not by a comment.

The third and fourth are the ones people miss. A comment can be entirely accurate, entirely present-tense, free of every ticket number and iteration label, and still be wrong for the spot it occupies.

Read the companion files first

On first use in a session, before any other step, read every companion file in this skill's directory. The summaries in this file are reminders of text you have already read, never a substitute.

• length-and-doc-comments.md — the full text of tenets 1, 2, 3, 4 and 6 and the sibling rule, with the worked examples: an eight-line "list of rules" and its two-line rewrite; a bulleted "decision table" that fails the row test and the body-match test next to one that passes; an editor-addressed "never do X" block turned into an assertion in the existing test plus one line; a comment that names its own body; the per-language table of what a long comment looks like in that language's own code; the doc-comment syntaxes and section conventions. Re-read it before keeping any comment over two lines, writing a doc comment on a public item, or writing the test behind an editor-addressed comment.
• ratio-and-ledger.md — the counting procedure for the ratio check and the format and fields of the long-comment ledger. Re-read it before finishing any change.
• reviewing-comments.md — the procedures for verifying what a comment claims, fixing code before commenting it, reviewing comments in a diff, and auditing in bulk. Re-read it before any review or sweep.