Date: 2025-12-23

Status

Accepted

Intent and Scope

This Architecture Decision Record defines a documentation-first, narrative-heavy source code commenting standard intended for use in projects that employ AI/LLM-assisted code generation or modification.

This ADR is deliberately project-agnostic. It does not assume the presence of other Architecture Decision Records, specific architectures, or particular tooling. It is intended to be reusable across projects, teams, and organizations.

The standard applies both to:

• newly written code, and
• existing code that is being documented, refactored, or reviewed with AI.

This ADR is intentionally verbose. Verbosity is a design choice, not an accident.

Core Premise

Source code is read far more often than it is written.

It is read:

• by junior developers,
• by tired developers,
• by stressed developers during incidents,
• by maintainers returning to code months or years later,
• and increasingly, by reviewers validating AI-generated changes.

This ADR assumes a human reader who is:

• short on time,
• under cognitive load,
• and not immersed in the original author’s mental context.

The goal of this standard is not elegance. The goal is comprehension under stress.

The Problem This ADR Addresses

AI/LLM-generated code frequently exhibits the following failure patterns:

• Minimal or missing comments
• Comments that restate syntax instead of explaining intent
• Loss of “why” during refactors
• Destructive rewrites when asked to “add documentation”
• Stubbed or replaced function bodies
• Silent removal of edge-case handling
• Overconfident tone masking incorrect behavior

These problems are not hypothetical. They occur regularly in real workflows.

This ADR exists to counteract those tendencies explicitly.

Guiding Principle

Documentation is architecture.

Comments and docstrings are not decorative. They are part of the system’s safety, maintainability, and incident-prevention surface.

This ADR adopts an intentionally extreme posture:

‍Target approximately two lines of meaningful documentation for every line of executable code.

This ratio is a guiding norm, not a rigid metric. The standard is met when a reader can understand both what the code does and why it exists without reverse-engineering behavior.

Human-Centered Design Perspective

This ADR centers the experience of a tired or stressed human.

That perspective drives several deliberate choices:

• Redundancy is allowed.
• Obvious facts may be restated if they reduce cognitive load.
• Trade-offs are explained even if they seem “obvious” to experts.
• Failure modes are described explicitly.
• Non-goals are documented to prevent false assumptions.

Clarity is prioritized over cleverness.

Documentation Density and Narrative Style

Code should read like a book written in plain language.

This means:

• complete sentences,
• consistent structure,
• and an explanatory tone.

Documentation SHOULD explain:

• motivation,
• constraints,
• safety posture,
• and consequences.

Documentation SHOULD NOT:

• merely label code blocks,
• rely on the reader to infer intent,
• or assume prior familiarity with the system.

Mandatory Documentation Targets

The following MUST be documented in all applicable languages:

• File/module headers
• Public classes
• Public functions and methods
• Non-trivial private helpers
• Configuration variables (environment variables, flags, config keys)
• Policy-defining constants
• Non-obvious data structures
• Safety mechanisms (dry-run modes, validation, guards)
• Edge cases and exceptional behavior

Undocumented behavior is considered a defect.

Required Documentation Content

Where applicable, documentation SHOULD include:

• Purpose and scope
• Background and motivation
• Inputs and outputs (types, shapes, semantics)
• Preconditions and assumptions
• Invariants that must always hold
• Failure modes and error handling
• Security or privacy considerations
• Configuration precedence and defaults
• Non-goals and excluded behaviors
• Concrete examples that resemble real usage

Not every section applies everywhere, but omissions should be intentional.

Structured Commenting (Doxygen-Style)

This ADR adopts a Doxygen-style conceptual structure across languages.

Exact syntax varies by language, but the following concepts should be present: