Code Documentation
debt(d7/e5/b5/t5)
Closest to 'only careful code review or runtime testing' (d7). While phpcs and phpmd are listed in detection_hints, they can only catch missing PHPDoc blocks or comment formatting issues — they cannot detect whether documentation explains 'why' vs 'what', whether it's accurate, or whether architectural decisions are recorded. The automated field explicitly says 'no'. Detecting documentation quality requires human code review or the painful experience of onboarding new team members who struggle.
Closest to 'touches multiple files / significant refactor in one component' (e5). The quick_fix suggests a mindset shift ('document the why not the what'), but actually fixing documentation debt means reviewing and rewriting comments across multiple files, creating ADRs, updating README files, and establishing new documentation practices. It's not architectural rework, but it's more than a localized fix — it touches many touchpoints where decisions were made without context.
Closest to 'persistent productivity tax' (b5). Poor documentation applies across web and cli contexts per applies_to, and creates ongoing friction: new team members take longer to onboard, developers re-debate solved problems (per common_mistakes about missing ADRs), and everyone spends extra time reverse-engineering intent. It doesn't define the system's shape, but it persistently slows down many work streams.
Closest to 'notable trap' (t5). The misconception explicitly states 'Good code does not need documentation' — this is a documented gotcha that most developers eventually learn is false. Many developers believe self-documenting code eliminates the need for comments, failing to distinguish between 'how' (readable from code) and 'why' (architectural decisions, constraints, external dependencies). This trap is well-known but still catches people.
Also Known As
TL;DR
Explanation
Good documentation exists at multiple levels: inline comments for non-obvious why decisions, PHPDoc for API contracts, README files for setup and usage, Architecture Decision Records (ADRs) for significant design choices, and runbooks for operational procedures. The best documentation is up-to-date, co-located with the code it describes (or linked from it), and treats clarity as a design goal. Documentation that explains what rather than why is usually a sign the code itself should be made clearer.
Common Misconception
Why It Matters
Common Mistakes
- Documentation that explains what (readable from code) instead of why (not readable from code).
- Docs that are out of date because they live separately from the code they describe.
- No ADRs (Architecture Decision Records) — future developers re-debate the same decisions without context.
- Over-documenting obvious code and under-documenting complex or non-obvious decisions.
Code Examples
// Documentation of what — useless:
// Increments the counter by 1
$counter++;
// Documentation of why — valuable:
// Counter starts at 1, not 0, because downstream billing system
// uses 1-based page numbers and we cannot change that API contract.
// See ADR-0042 for context.// PHPDoc — inline API documentation
/**
* Place an order for the authenticated user.
*
* Validates cart contents, applies loyalty discounts, charges payment method,
* and dispatches OrderPlaced event. The cart is cleared on success.
*
* @param Cart $cart Validated cart (must not be empty)
* @param PaymentMethod $payment Tokenised payment method
* @return Order The persisted order with status 'pending'
*
* @throws CartEmptyException If the cart has no items
* @throws PaymentFailedException If the charge is declined
*/
public function place(Cart $cart, PaymentMethod $payment): Order {}
// README structure:
// 1. What this project does (1 paragraph)
// 2. Quick start (copy-paste to get running)
// 3. Environment variables (.env.example documented)
// 4. Architecture overview
// 5. Contributing guide