comment

Comment Style

One principle across all languages: comments state what IS. They never narrate what is happening, restate what the code says, or editorialize.

The deletion test: if the comment disappears, does the reader lose information they could not get from reading the code? If no, delete it.

Style guides to load

Read the relevant guide before making comment/doc decisions. These are the canonical sources; do not rely on memory of their contents.

Language	Guide path
Root (all languages)	style/style.md
Python	docs/src/style/python.mdx — see ## Documentation section
TypeScript	style/typescript.md
Rust	docs/src/style/rust.mdx
Go (guide)	docs/src/style/go/guide.mdx
Go (decisions)	docs/src/style/go/decisions.mdx — see documentation section

Read style/style.md always. Then read the language-specific guide for the file you are editing.

---

Cardinal rule: write for the least experienced reader

Code and comments should be immediately understandable by both a novice and an expert. A reader should never have to leave the file to figure out what the file does or why it exists.

This is the bar: if someone opens this file cold, with no prior context about the project, can they answer these questions within 30 seconds?

1. What does this module do?
2. Why does it exist?
3. Where does it fit in the system?

If the answer requires reading five other files, the module doc has failed.

Short sentences, plain words

MOST IMPORTANT RULE: write like a sixth grader. One idea per sentence. No subordinate clauses when two sentences will do.

Bad:  "The guest kernel sends FUSE requests over virtio-fs, a virtio
      device that carries FUSE operations over shared memory instead
      of a network socket, and fuse-backend-rs deserializes them and
      calls our FileSystem trait impl."

Good: "The guest kernel sends FUSE requests over virtio-fs. virtio-fs
      uses shared memory, not network packets. fuse-backend-rs
      deserializes the requests. We answer them."