Skip to content
Documentation

ADR-021: Self-Documenting Code Examples

Decision

Every code example in any documentation surface is self-documenting — fully understandable in isolation by a junior developer or an LLM with no surrounding context.

Key rules

  • Every code example carries a header comment: what it does plus a link to the official docs for the library or API it uses.
  • Add inline comments on every non-obvious line — never leave magic numbers, unexplained options, or hardcoded IDs, version numbers, or timeouts uncommented.
  • The self-documenting rule applies to every code block in every .md / .mdx file — no exceptions for “simple” or single-node examples.
  • A decorative or partial example is worse than none: show working integration code, not a sketch.

Code patterns

// Create a child logger with request context — one per inbound request.
// Docs: https://getpino.io/#/docs/child-loggers
const log = baseLogger.child({
  request_id: ctx.requestId,   // ULID — generated at the edge
  trace_id: ctx.traceId,       // OTel hex 32 — from incoming W3C trace header
})

Why

A consumer who copies an example expects working integration code, and an LLM reading the same surface inherits any gap. Header comments, inline annotations, and called-out magic values make each block legible standalone. Per-component LLM context is no longer hand-authored — agents read it live from the dmwd Storybook MCP, TypeScript docgen, and stories (see ADR-026).

Applies when

You are adding any code example to an ADR, doc page, or Storybook docs surface.

  • ADR-017 — documentation truthfulness contract.
  • ADR-016 — Storybook information architecture and navigation.