commenting-codelisted

# Commenting Code ## Core principles - Improve naming and structure first; do not comment around unclear code. - Add comments only when they prevent a likely misunderstanding. - Prefer stable intent over volatile implementation narration. - Keep comments concise, concrete, and testable. ## Workflow 1. **Decide whether a comment is needed.** Add a comment when behavior could be misread and lead to defects (for example: invariants, ordering constraints, concurrency assumptions, retries/timeouts, side effects, or error semantics). 2. **Choose the right layer.** - **Interface docs**: caller-visible contract and usage semantics. - **Implementation comments**: maintainer-facing rationale and invariants. - **Cross-module notes**: decisions that span module boundaries. 3. **Write the smallest high-signal comment.** Lead with the most important fact. Include concrete details (units, bounds, ordering, failure behavior) when relevant. 4. **Remove low-value comments.** Delete tautologies, stale comments, hedging, and commented-out code. 5. **Keep docs synchronized with behavior.** If behavior changes, update comments/docs in the same change. ## What to include ### Interface docs (caller-facing) Document what callers can rely on: - behavior guarantee - input constraints and units - return semantics (including edge cases) - error/failure semantics - side effects and mutation behavior - concurrency or idempotency semantics when relevant ### Implementation commen