Documentation and ADRs

Overview

Document the why behind decisions, not just the code. Architecture Decision Records (ADRs) capture the context, alternatives, and consequences of significant decisions so future developers understand why the system is shaped the way it is.

When to Use

• Making an architectural trade-off (e.g., Room vs DataStore, Compose vs XML)
• Changing a public API or module boundary
• Shipping a user-facing feature with non-obvious implementation choices
• Onboarding new developers to the project
• After a post-mortem or incident that changed the architecture

Skip when: The change is self-explanatory from the code and commit message.

Core Process

Architecture Decision Records (ADRs)

1. Match the existing convention first. Before creating an ADR, look for one already in the repo — existing ADRs, rules in AGENTS.md/CLAUDE.md, ADR tooling such as an .adr-dir file. An established convention overrides the defaults below:

   • Location and format — e.g. docs/adr/, docs/architecture/decisions/, a MADR layout, an adr-tools setup. Match the directory, extension, and markup.
   • Numbering and naming — continue the existing sequence and filename pattern; don't restart at 0001 or introduce a second scheme.
   • Section headings — reuse the project's heading set rather than imposing this template's.

   If the evidence conflicts, surface the conflict instead of silently adding another scheme.

2. With no convention, ADRs live in docs/decisions/ with sequential numbering:

   docs/decisions/
   ├── 0001-use-compose-over-xml.md
   ├── 0002-adopt-mvi-for-complex-screens.md
   ├── 0003-room-migration-strategy.md
   └── 0004-modularization-approach.md

3. ADR template: (new ADRs start at Proposed; move to Accepted once agreed)

# ADR-NNNN: Title

## Status
Proposed | Accepted | Deprecated | Superseded by ADR-XXXX

## Context
What is the issue or decision we're facing? What forces are at play?

## Decision
What did we decide to do?

## Alternatives Considered
### Alternative A: [Name]
- Pros: ...
- Cons: ...

### Alternative B: [Name]
- Pros: ...
- Cons: ...

## Consequences
### Positive
- ...

### Negative
- ...

### Risks
- ...

4. Never delete old ADRs — supersede them with new ones that reference the old decision:

   ## Status
   Superseded by [ADR-0007](0007-switch-to-kmp.md)

Inline Documentation

5. Document intent, not mechanics:

// BAD: increments counter by one
counter++

// GOOD: Rate-limit API calls to avoid 429 responses from the backend.
// The backend enforces a 10-request-per-second limit per client.
if (requestCount >= MAX_REQUESTS_PER_SECOND) {
    delay(rateLimitWindow)
}

6. When to add inline comments:
   • Non-obvious business logic
   • Platform workarounds (// Workaround for API 28 camera permission bug)
   • Performance-critical code paths
   • Regex patterns or complex algorithms
7. When NOT to add comments:
   • Code that reads clearly (self-documenting)
   • Commented-out code (delete it — git has history)
   • "TODO" without an issue reference (create the issue)

API Documentation

8. Public APIs get KDoc:

/**
 * Fetches the user's profile from the remote API, falling back to
 * the local cache if the network is unavailable.
 *
 * @param userId The unique identifier of the user.
 * @return The user profile, or `null` if not found in cache or remote.
 * @throws NetworkException if the request fails and no cache exists.
 */
suspend fun getUserProfile(userId: String): UserProfile?

9. Document module boundaries — each module's README.md should describe:
   • Purpose of the module
   • Public API surface
   • Dependencies (what it depends on, what depends on it)

Common Rationalizations

Red Flags

• Architectural decisions without ADRs
• Inline comments explain what instead of why
• Commented-out code blocks
• TODOs without issue references
• Public APIs without KDoc
• Stale documentation that contradicts current implementation
• ADRs deleted instead of superseded
• A second ADR location or numbering scheme introduced next to an existing one

Verification

• Significant architectural decisions have ADRs — in the project's existing ADR location and numbering, or docs/decisions/ if none exists
• ADRs include context, alternatives, and consequences
• Old ADRs are superseded, not deleted
• Inline comments explain why, not what
• No commented-out code
• Public APIs have KDoc with @param, @return, @throws
• Module boundaries documented