---
title: "Keep docblocks only for what types cannot · Agent Wranglers"
url: https://agentwranglers.se/playbook/architecture/comments/useful-docblocks
updated: 2026-10-20
licence: "All rights reserved"
---

# Keep docblocks only for what types cannot say

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

- Level: Recommended
- Chapter: [Comments](https://agentwranglers.se/playbook/architecture/comments)
- Rule: Write a docblock only when it adds a type, a contract or a unit the language cannot express. Delete docblocks that repeat the signature.
- How: Use types in the signature where the language has them. Keep a docblock for generic types such as `list<Order>`, for thrown exceptions, and for units like cents or seconds. Public library functions may keep a one-line summary.
- Check: A linter flags docblocks that only repeat the parameters. Examples are PHP-CS-Fixer's `no_superfluous_phpdoc_tags` and ESLint's `jsdoc/no-types` in TypeScript files.

Example:

```php
// Bad: says nothing the signature does not
/**
 * @param int $orderId the order id
 * @return Order the order
 */
public function find(int $orderId): Order

// Good: adds what the type system cannot say
/** @return list<Order> newest first, at most 50 */
public function recentFor(CustomerId $customer): array
```

```python
# Bad: repeats the signature
def find(order_id: int) -> Order:
    """Find the order with the given order id and return the order."""

# Good: says what the types cannot
def recent_for(customer: CustomerId) -> list[Order]:
    """Newest first, at most 50."""
```

**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/useful-docblocks`.

- Previous: [Say why, not what](https://agentwranglers.se/playbook/architecture/comments/comments-say-why)
- Next: [Link every TODO to a ticket](https://agentwranglers.se/playbook/architecture/comments/todos-with-tickets)
- [Comments](https://agentwranglers.se/playbook/architecture/comments)