Code Comments

Write code so the structure explains the what. Write comments so future humans and agents understand the why, why not, what must stay true, and what already happened here.

Core Rule

Use this order:

1. Rename, extract, reorder, or delete code until the intent is obvious
2. Add a comment only when the missing context cannot live in code
3. Put the shortest useful comment as close as possible to the code
4. Keep the comment short, local, and durable

Good comments reduce wrong edits. Great comments stop humans and agents from repeating old mistakes.

The Comment Test