Say why, not what

How to do it

Before writing a comment, ask if it would still be true after a rename. If it describes the code, improve the code instead. If it records a decision, keep it short and link the source, such as a bug report or a measurement.

Example

# Bad: repeats the code
# add one to the count
count += 1

# Good: a reason the code cannot show
# The payment provider retries webhooks for 72 hours, so keep seen IDs that long.
SEEN_WEBHOOK_TTL = timedelta(hours=72)

// Bad: repeats the code
// add one to the count
count += 1;

// Good: a reason the code cannot show
// The payment provider retries webhooks for 72 hours, so keep seen IDs that long.
const SEEN_WEBHOOK_TTL_MS = 72 * 60 * 60 * 1000;

How to check

Reviewers mark any comment that restates the next line. A comment-share script, such as the one in the first rule, keeps the total low.