Code Documentation Standards
debt(d5/e3/b5/t5)
Closest to 'specialist tool catches it' (d5). The detection_hints list phpcs, phpstan, psalm, and phpdoc — these are specialist static analysis and linting tools that can catch missing docblocks or @param/@return mismatches, but they won't catch the subtler problems like outdated comments contradicting actual code or missing 'why' explanations, which require code review.
Closest to 'simple parameterised fix' (e3). The quick_fix describes writing docblocks for public API methods with @param, @return, @throws annotations — a localised but repeated effort across multiple methods. It's more than a one-line patch but doesn't require cross-cutting refactors; it's a pattern applied method by method within a codebase.
Closest to 'persistent productivity tax' (b5). Documentation standards apply across all contexts (web, cli, queue-worker) and affect every developer on every PR. Poor standards accumulate decay over time — outdated comments, missing architecture decisions — slowing down many work streams, but they don't architecturally define the system's shape the way a core abstraction would.
Closest to 'notable trap' (t5). The misconception field identifies the canonical wrong belief: 'More comments means better documentation.' This is a well-known and documented gotcha — developers commonly write noise comments restating code rather than explaining why, and outdated comments are worse than none. This is a broadly understood trap that most developers eventually learn through experience.
Also Known As
TL;DR
Explanation
Documentation has levels: code (names, structure), inline comments (why, not what), docblocks (API contracts, @throws, complex types), README (project overview, setup, architecture), ADRs (architectural decisions), and external docs (user-facing). Anti-pattern: comments that restate the code ('increment i by 1 // i++'). Valuable comments: explain why a non-obvious approach was chosen, document known limitations, reference the issue that required a workaround, and explain complex algorithm steps.
Common Misconception
Why It Matters
Common Mistakes
- Comments that describe what the code does rather than why.
- Outdated comments that describe old behaviour after refactoring — wrong documentation is worse than none.
- No README — the most common documentation gap in PHP projects.
- Architecture decisions undocumented — 'why did we choose this approach?' answered by 'no idea, it was here when I joined'.
Code Examples
// Comments that add zero value:
$i++; // Increment i
$users = []; // Initialize array
// Check if user is admin:
if ($user->role === 'admin') {
// They are admin
}// Comments that explain why:
// Rate limit to 5 req/min per IP — prevents credential stuffing.
// See: https://security.example.com/incidents/2025-001
if ($rateLimiter->isExceeded($ip)) {
throw new RateLimitException();
}
// Use bcrypt cost 14 not 12 — server benchmark showed negligible
// difference at 14 but makes offline dictionary attacks 4x slower.
$hash = password_hash($password, PASSWORD_BCRYPT, ['cost' => 14]);