wise-code-comments

Code-comment standards

Standing contract for every code comment and docstring wise writes, in any language. No slash command - it is auto-consulted whenever comments are written or edited.

The rules (MUST)

1. ELI5 wording. Write so a developer new to the codebase understands the comment on first read. Plain words, short sentences, the simplest domain term that carries the fact. No jargon a newcomer would have to look up when a common word works.

2. Concise. One comment states one fact, once. If the comment can lose a word without losing the fact, lose the word. A comment that restates what the line below obviously does is deleted, not shortened.

3. Present-tense facts only. Describe what the code does or what constraint it obeys now. The comment must stay true when read in isolation years later by someone with no access to the project's history.

4. No history. Never explain how the code came to be: no ticket numbers as narrative ("in PROJ-12345 we refactored this to ..."), no "previously this used X", no "changed to fix the bug where ...", no "now correctly handles ...". History lives in commit messages, PR descriptions, and tickets.

5. No author-to-reviewer talk. A comment never justifies the change to whoever is reading the diff ("this is safe because we already validated above"). If the fact matters to every future reader, state the fact itself; otherwise put it in the PR.

What a comment is for

The code shows what it does. A comment earns its place only when it carries something the code cannot show:

• a constraint ("callers hold the lock before entering")
• a non-obvious reason ("the API returns 200 on partial failure, so check the body")
• a unit, range, or format ("timeout in milliseconds")
• a warning ("order matters: flush before close or data is lost")

Examples

Bad (history, narration):

// In ticket WISE-12345 we refactored this in order to avoid the
// race condition we had with the old cache implementation.
func loadConfig() {...}