Comments First

Comments hold what was in the designer's head but can't live in code. Without an interface comment there is no abstraction: callers have to read the body.

Mode A — new code (comments first)

1. Class or module interface comment: what abstraction it provides, what one instance represents, and its limits.
2. Signatures plus interface comments for the main public methods. Leave the bodies empty.
3. Iterate on those comments until they are short and complete. If a comment can't be both, the design is wrong. Fix the design, not the prose.
4. Comment the key fields, then write the bodies. Every new method gets its comment before its body.

Mode B — audit existing code

Check in this order: