---
name: craft-comment
description: What a comment is for, what shape it takes, and the space around code that means no comment is needed. Applies to any language, not only shell.
---

# Skill: Craft Comment

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

## 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, narrowing evenly,** once there is more than one sentence to say. The two steps
   stay within three of each other, so the block reads as one shape rather than three accidents.
   `taper.md` carries the loop, and the measurement behind the number.
   **Three lines is a shape, never a target.** Padding one sentence into three to make it narrow is
   the waste `economy` names, wearing craft.
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](taper.md) for the loop, and [comments](../craft-sh/comments.md) for before and after.