Code Commenting

Workflow

1. Improve code clarity first (naming, structure, refactors) before adding comments.
2. Decide whether a comment is needed using the "Comment Decision Rules" below.
3. Add comments that explain intent, constraints, and non-obvious trade-offs (the "why").
4. Use standard doc-comment formats for public APIs and important interfaces.
5. Review for staleness, redundancy, and risk (commented-out code, secrets, misleading claims).
6. Keep comments maintained: update or remove when code changes.

Principles

• Prefer self-documenting code: comments are not a substitute for clarity.
• Comment the "why" (intent, constraints, context), not the "what".
• Treat comments as code: they need review, tests (when applicable), and maintenance.

Comment Decision Rules