Code Documentation

Documentation drifts toward two failure modes: silence (public APIs nobody can use without reading the implementation) and noise (prose that repeats what the code already says and rots the first time the code changes). This skill prevents both with hard per-element line caps. The amount of documentation an element gets is a function of its size and how obvious it is, never a fixed template applied uniformly.

See references/documentation-formats.md for the full per-language format reference with additional examples.

Contents

• Workflow
• Core Rules Summary
• Code Examples
• Common Mistakes
• Review Checklist
• References

Workflow

Choose the path that matches the request:

1. Document new code

1. Identify the element type: package/module, struct/class/interface, constant/variable, field/property, function/method, or inline step inside a body.
2. Classify each callable as trivial, medium, or complex using Function tiers. The tier caps descriptive prose; it never lowers documentation below what a caller needs.
3. Apply the ceiling from Length caps by element. No function doc comment exceeds 2 prose lines, whatever the complexity.
4. Move every caller-visible parameter, return, and error into a structured entry — one entry per line, exempt from the prose cap.
5. Write the language-native format from references/documentation-formats.md, in the language-native position. Never use trailing comments.
6. Leave trivial, unexported, self-evident elements undocumented.
7. Run the Review Checklist before delivering.

2. Improve existing documentation

1. Find public modules and exported symbols shipping silent, and document them to the cap.
2. Cut prose that restates the implementation, then confirm the remaining lines still carry every caller-visible fact rather than hiding it in the body.
3. Delete routine field, property, and interface-member comments; re-encode units, formats, ranges, defaults, and enum options in names, dedicated types, validation, or the type-level contract.
4. Unwrap comments that were split to satisfy a column limit so each fact sits on one complete line.
5. Replace external links with a self-contained contract stated in terms of the code.

3. Review existing documentation

Trace each element through visibility, tier, prose cap, structured entries, placement, field-comment justification, and staleness against the current body. Rerun the checklist after each correction.

Core Rules Summary

Length caps by element

Function tiers

A medium function fully explained in 1 prose line does not need a padded second line to use the budget.

Non-negotiables

Always document when applicable

Assumptions, side effects, performance costs, concurrency constraints, null/None behavior, and the reason behind a magic number stated on one line above its declaration.

Caller-visible facts belong in the declaration contract. Implementation-local reasoning belongs inline at the exact step it explains, never in the declaration, even when prose budget remains.

Code Examples

Structure documented once, fields left bare

// PaymentRequest captures provider-independent input for one payment attempt.
type PaymentRequest struct {
    AmountCents             int64
    Currency                CurrencyCode
    Method                  PaymentMethod
    RetryOnTransientFailure bool
    id                      string
}

Units, currency format, method options, and retry behavior belong in names, dedicated types, and validation — not in one comment per field.

The extreme-ambiguity field exception

// LegacyAttribute preserves stored records that encode values as either UTF-8 text or base-10 integers.
type LegacyAttribute struct {
    // Value accepts either a UTF-8 string or a base-10 integer; every other runtime type is rejected.
    Value any
}

Value qualifies only because any hides two legal runtime types and a compatibility constraint prevents a precise type. A merely broad or poorly chosen type is not enough: improve the model instead.

Interface documented once, members left bare

// InvoiceRepository persists invoice records and their processing outcomes.
type InvoiceRepository interface {
    Create(ctx context.Context, data core.Invoice) (core.Invoice, error)
    UpdateStatus(ctx context.Context, id ULID, status string, officialID string) error
    GetByID(ctx context.Context, id ULID) (core.Invoice, error)
}

/** Describe the persisted shape of one invoice as returned by the invoices API. */
interface InvoiceRecord {
    id: string;
    status: InvoiceStatus;
    totalCents: number;
    issuedAtUtc: string;
    cancel(reason: CancellationReason): Promise<void>;
}

The member list is the contract. Facts about what each operation returns or raises go on the concrete implementations, under the function rule.

Complex function, still capped at 2 prose lines

// SyncInventory reconciles warehouse and e-commerce inventory; conflicts compare each system's inventory_updated_at normalized to UTC epoch seconds, with the highest value winning and ties favoring the warehouse.
// It returns partial results alongside a non-nil error whenever synchronization fails for one or more individual SKUs.
func SyncInventory(products []string, source string) (*Summary, error) {
    // Normalize once so conflict detection and writes use identical SKU keys.
    valid := normalize(products)

    for sku, conflict := range detectConflicts(valid, source) {
        resolve(sku, conflict)
    }
    ...
}

Structured entries carrying the contract

def process_payment(amount: float, method: str, retry: bool = True) -> dict:
    """Process a payment using the selected method; retry only transient failures.

    Args:
        amount: Positive amount in USD.
        method: Payment method; accepts 'card', 'paypal', or 'transfer'.
        retry: Whether to make up to two additional provider calls after a transient failure; false makes one attempt.

    Returns:
        Payment status, transaction ID, and processed_at_utc as a YYYY-MM-DDTHH:MM:SSZ string.

    Raises:
        ValueError: If amount or method is invalid.
        PaymentError: If the sole attempt fails while retry is false, or every attempt fails while retry is true.
    """
    return payment_provider.process(amount=amount, method=method, retry=retry)

One complete line per entry — never compacted together, never wrapped to a column limit.

Exported constant, exactly one line

// DefaultRetryLimit bounds transient provider retries before Charge returns an error.
const DefaultRetryLimit = 2

Constants and variables are symbols, not data-structure properties, so the field prohibition does not apply to them.

Inline comments that earn their line

# Convert epoch seconds at the boundary so every internal timestamp is timezone-aware UTC.
timestamp = datetime.fromtimestamp(response.timestamp, tz=timezone.utc)

# Traverse in reverse so each removal preserves indexes that remain to be visited.
for index in range(len(items) - 1, -1, -1):
    if should_remove(items[index]):
        del items[index]

# Reserve five seconds of the execution budget for cleanup.
REQUEST_TIMEOUT_SECONDS = 25

Against the same steps, # Increment counter, # Iterate over users, and # Return True add nothing and are prohibited.

Private and self-evident, left undocumented

def _get_user_name(user):
    return user.name

A docstring here would restate the name and the body. The public-symbol rule does not reach it.

Common Mistakes

Review Checklist

• Public coverage: Every public package/module and exported type, function, concrete method, constant, and variable is documented.
• Declaration caps: Packages/modules and types have 1 prose line, rarely a second line for a hard invariant.
• Constant cap: Every exported constant and variable has exactly 1 prose line.
• Prose ceiling: No function/method doc comment exceeds 2 lines of descriptive prose, regardless of complexity.
• Tier applied: Every documented callable was classified trivial/medium/complex and respects that tier's cap.
• Structured entries: Each documented parameter, return, and error occupies its own line and is not counted against the prose cap.
• No width wrapping: No comment was split or truncated to satisfy a column limit.
• Members bare: No routine field, property, or interface-member comments, whatever the visibility.
• Interfaces once: Each interface carries a single declaration line and no comment on any method signature.
• Field exception justified: Any field comment is exactly 1 line and driven by irreducible ambiguity between multiple legal runtime types.
• Placement: Declaration comments sit immediately above declarations, Python docstrings are first statements, inline comments precede their step, and no trailing comments remain.
• Silence where due: Trivial, unexported, self-evident elements are left undocumented rather than padded to a template.
• Contract completeness: Non-obvious errors/exceptions the callable can produce are documented.
• Special cases: Applicable assumptions, side effects, performance costs, concurrency constraints, and null/None behavior are stated; magic numbers carry a reason.
• Layer separation: Caller-visible edge cases live in the declaration contract; implementation-local reasoning lives inline at the relevant step.
• Inline discipline: Inline comments explain "why", stay single-line, and no large commented block sits inside a body.
• Freshness: No redundant, obvious, or outdated comments remain.
• Language: Documentation uses the repository's established language, or English when none exists, without mixing within one public API.
• Self-contained: No links or references to external documentation or sources.

References

• Full per-language format guide: references/documentation-formats.md