---
title: "Comments · Agent Wranglers"
url: https://agentwranglers.se/playbook/architecture/comments
updated: 2026-10-20
licence: "All rights reserved"
---

# Comments

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

> Let names and small functions carry the meaning. Keep a comment only for a reason the code cannot show, and let version control keep the history.

**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`.

## Required

- [Refactor clever code instead of explaining it](https://agentwranglers.se/playbook/architecture/comments/refactor-clever-code): When a block needs a comment to be understood, rewrite it so it reads plainly. Never leave a puzzle with a note beside it.
- [Delete commented-out code](https://agentwranglers.se/playbook/architecture/comments/no-commented-out-code): Never commit code that is commented out. Delete it, because version control already keeps every old line.

## Recommended

- [Let the code explain itself](https://agentwranglers.se/playbook/architecture/comments/self-documenting-code): Name things so the code explains itself, and write a comment only for a reason the code cannot show.
- [Keep change history out of comments](https://agentwranglers.se/playbook/architecture/comments/no-journal-comments): Keep change logs, author names, dates and ticket histories out of the code. Version control records who changed what and why.
- [Say why, not what](https://agentwranglers.se/playbook/architecture/comments/comments-say-why): 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.
- [Keep docblocks only for what types cannot say](https://agentwranglers.se/playbook/architecture/comments/useful-docblocks): Write a docblock only when it adds a type, a contract or a unit the language cannot express. Delete docblocks that repeat the signature.
- [Link every TODO to a ticket](https://agentwranglers.se/playbook/architecture/comments/todos-with-tickets): A `TODO` or `FIXME` comment names a ticket, or it is not merged. Loose notes in the code are never planned and never found.

- Previous: [Names and functions](https://agentwranglers.se/playbook/architecture/names-and-functions)
- Next: [Errors and nulls](https://agentwranglers.se/playbook/architecture/errors-and-nulls)
- [All chapters](https://agentwranglers.se/playbook/architecture)