Code Documentation Standards

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]);

References

• ↗ https://www.php-fig.org/psr/psr-5/

Tags

Related Terms