Craft Comment

Skill: Craft Comment

"A comment you had to write is a name you did not."

The rule in one sentence: a comment of three lines makes each line three bytes shorter than the one above it. One line and two lines are fine and are not graded. bin/taper.sh grades this repository's own comments; elsewhere it is craft.

The Standard

1. Carry a discovery, never narration. # herd start stops the data services earns its line. # ── Step 3 ── above a line printing "Step 3" does not.
2. Needing one is evidence against the code. A comment explaining what a body does means the name is wrong or the body is two jobs. Fix that first and the comment leaves on its own. A preamble longer than what it introduces is the clearest form of the tell.
3. One sentence, when one sentence does it. No fence and no bold — the blank line already separated it, and the sentence that matters goes first.
4. Three lines, each exactly three bytes shorter than the one above it. Not about three, and not an even step of any size — three, twice. A block that steps by eighteen is a triangle, and a triangle is what this refuses. taper.md carries the loop. Two lines when three will not land honestly. Padding a sentence to reach the number is the waste economy names, wearing craft — and a two-line comment is not graded, because rule 3 already prefers it. What is never allowed is a three-line block that misses.
5. Let it breathe. Blank lines inside a body group steps into thoughts, so it reads as three moves rather than eleven lines. A body with no blank line is held breath. Breathing is space, not words — the opposite mistake is filling the space that was doing the work.
6. A split moves its comments. After extracting, the parent keeps only what the parts do not say. Facts left behind get read twice and edited once.
7. Say why a defensive line survives. A guard with no reason reads as redundant, and redundant is what gets simplified away.

Examples

See taper for the loop, and comments for before and after.