---
title: "Say why, not what · Agent Wranglers"
url: https://agentwranglers.se/playbook/architecture/comments/comments-say-why
updated: 2026-10-20
licence: "All rights reserved"
---

# Say why, not what

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

- Level: Recommended
- Chapter: [Comments](https://agentwranglers.se/playbook/architecture/comments)
- Rule: A comment states a reason the code cannot show, such as a bug in another system, a legal rule or a measured trade-off. It never repeats what the code does.
- How: 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.
- 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.

Example:

```python
# 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)
```

```ts
// 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;
```

**For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers architecture playbook: https://agentwranglers.se/playbook/architecture/comments/comments-say-why`.

- Previous: [Keep change history out of comments](https://agentwranglers.se/playbook/architecture/comments/no-journal-comments)
- Next: [Keep docblocks only for what types cannot say](https://agentwranglers.se/playbook/architecture/comments/useful-docblocks)
- [Comments](https://agentwranglers.se/playbook/architecture/comments)