document-touched-code

Files (2)

• SKILL.md
• comment-patterns.md · references/

SKILL.md (first lines)

# Document Touched Code

Treat documentation as part of the implementation, not a later cleanup step.

When you add or materially change code, leave the touched area easier to understand than you found it: accurate doc comments on the touched methods/functions and focused local comments where the reasoning would otherwise be expensive to re-derive.

## Default Standard

1. Add or update doc comments on every touched exported function, class method, constructor, and materially changed private method.
2. In JavaScript or TypeScript, use JSDoc. In other languages, use the closest native doc-comment format.
3. Add short section comments near non-trivial logic you added or materially changed.
4. Keep comments focused on intent, assumptions, invariants, ordering, edge cases, and decision points.
5. Rewrite or remove stale comments when behavior changes.
6. Do not leave touched code less documented than the surrounding codebase standard.

## Workflow

1. Identify every method, function, or class member you touched.
2. Update doc comments so the signature, parameter meaning, return value, side effects, and important invariants still match reality.
3. Scan the changed logic for the places where a future maintainer would have to stop and mentally simulate the code.
4. Add one focused comment at those points, close to the code it explains.
5. Re-read the result and delete any comment that only repeats the next line instead of explaining why it exists.

## Where Comments Usually Matter

- Fallback ordering, cache precedence, and orchestration steps
- Dense predicates, validation branches, or conflict/rule evaluation
- Data normalization, identity matching, and shape conversion
- State transitions, DOM synchronization, and multi-step UI flows
- Code that preserves invariants or protects a revert baseline
- Places where the implementation intentionally does something non-obvious

## Comment Quality Rules

Do:

- Explain why the block exists or why the order matters.
- Call out assumptions, constraints, and edge-case handling.
- Use section comments to break long methods into meaningful phases.
- Keep wording specific enough that future edits can validate whether the comment is still true.

Do not:

- Narrate obvious line-by-line behavior.
- Add boilerplate doc comments that merely rename parameters.
- Leave outdated comments in place after changing behavior.
- Add comments everywhere indiscriminately; add them where comprehension would otherwise slow down.

## Quick Heuristics

- If a method signature changed, its doc comment probably needs an update.
- If a block took more than a quick glance to understand, it probably deserves a short local comment.
- If the code is already obvious from names and structure, prefer no comment.
- If a comment would be valid in almost any project, make it more specific.

## Reference

See [references/comment-patterns.md](references/comment-patterns.md) for short examples of strong doc comments and section comments.
Pair with [`clean-code-and-oop`](../clean-code-and-oop/SKILL.md) to keep function interfaces, class contracts, and types clean and self-describing.

From werlang/user-skills, MIT.

More from werlang/user-skills