---
title: "Refactor clever code instead of explaining · Agent Wranglers"
url: https://agentwranglers.se/playbook/architecture/comments/refactor-clever-code
updated: 2026-10-20
licence: "All rights reserved"
---

# Refactor clever code instead of explaining it

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

- Level: Required
- Chapter: [Comments](https://agentwranglers.se/playbook/architecture/comments)
- Rule: When a block needs a comment to be understood, rewrite it so it reads plainly. Never leave a puzzle with a note beside it.
- How: Replace bit tricks and dense one-liners with named steps. Pull a condition into a function whose name states the question, such as `isEligibleForRefund`. Name the parts of a long expression with local variables. Prefer a clear loop over a chain nobody can follow.
- Check: Reviewers ask one question for each comment that explains how code works. "Would a rename or an extracted function make this comment unneeded?" If yes, the review fails until the code is changed.

Example:

```js
// Bad: a clever line and a note to decode it
// true if the order is paid and shipped but not refunded
const ok = (o.flags & 6) === 6 && !(o.flags & 8);

// Good: the names say it
const isPaid = order => order.flags.has('paid');
const isShipped = order => order.flags.has('shipped');
const isRefunded = order => order.flags.has('refunded');
const isComplete = order => isPaid(order) && isShipped(order) && !isRefunded(order);
```

```python
# Bad
# skip weekends
days = [d for d in days if d.weekday() < 5]

# Good
def is_weekday(day): return day.weekday() < 5
working_days = [day for day in days if is_weekday(day)]
```

**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/refactor-clever-code`.

- Previous: [Let the code explain itself](https://agentwranglers.se/playbook/architecture/comments/self-documenting-code)
- Next: [Delete commented-out code](https://agentwranglers.se/playbook/architecture/comments/no-commented-out-code)
- [Comments](https://agentwranglers.se/playbook/architecture/comments)