Code Documentation

Overview

Code documentation explains intent, behavior, and usage. Good documentation helps onboarding, maintenance, and incident response.

Documentation Levels

• Inline comments for non-obvious logic
• API documentation for contracts and examples
• Module README files for setup and architecture context
• Runbooks for operational procedures

flowchart LR
    A[Code] --> B[Inline Notes]
    A --> C[API Docs]
    A --> D[Module README]
    A --> E[Runbooks]

Practical Example

/// <summary>
/// Retries transient failures with exponential backoff.
/// Use for network calls where intermittent failure is expected.
/// </summary>
public static async Task RetryWithBackoffAsync(
    Func<Task> operation,
    int retries = 3)
{
    for (var attempt = 1; attempt <= retries; attempt++)
    {
        try
        {
            await operation();
            return;
        }
        catch when (attempt < retries)
        {
            await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, attempt)));
        }
    }

Production Guidance

• Document why, not what
• Keep examples runnable and current
• Update docs in the same pull request as behavior changes

Common Pitfalls

• Stale documentation that contradicts code
• Over-commenting obvious lines
• Missing operational documentation for critical services

Key Takeaways

• Useful documentation accelerates maintenance and onboarding.
• Accuracy is more important than volume.
• Documentation should evolve with code changes.