documentation-and-adrs

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. 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
   

2. ADR template:

# 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
- ...

1. 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

1. 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)
}

1. 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