Code Comments and Inline DocumentationLesson 5.4

Writing effective README sections inside repositories

module-level documentation, directory README files, architecture decision records, codebase navigation docs, monorepo documentation, internal developer documentation

Internal Repository Documentation

Internal documentation — for contributors and teammates, not end users — follows different rules. The audience already has context. They need navigation, decision rationale, and maintenance guidance, not tutorials.

Module-Level READMEs

In large codebases and monorepos, every significant module or package deserves its own README:

## auth-service

Handles user authentication and session management.

### Owns
- JWT issuance and validation
- Session storage (Redis)
- OAuth provider integration

### Does NOT own
- User profile data (see `user-service`)
- Authorization/permissions (see `rbac-service`)

### Local development
```bash
npm run dev:auth
```

### Key files
- `src/jwt.ts` — Token creation and verification
- `src/session.ts` — Redis session management
- `src/oauth/` — Provider-specific adapters

Architecture Decision Records

Architectural decisions made once are forgotten and relitigated endlessly without documentation. An ADR records: the decision, the context, and the alternatives considered. Store them in docs/decisions/ as numbered Markdown files. Future contributors stop asking "why did you do it this way?" — they read the ADR.