Code Documentation

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

References

• ↗ https://www.divio.com/blog/documentation/
• ↗ https://adr.github.io/

Tags

Related Terms