Programming as Theory Building (Naur)

Details

Core Concepts:

Theory building: Programming is creating a mental model, not just writing code. The real program exists in developers' minds, not in the code.
Document the Why: Code shows what the system does. The theory captures why it is built this way — the reasoning, trade-offs, and domain understanding behind the design.
Theory decay: When original developers leave, the theory is lost. Written code alone cannot reconstruct it. This explains why maintenance by new teams is so difficult.
Complement to ADRs: ADRs document individual architectural decisions. Theory Building goes deeper: document the overarching understanding of why the system is shaped the way it is.
Communication is key: Theory must be shared through collaboration, conversation, and documentation that captures intent, not just structure.
Key Proponent: Peter Naur (Turing Award winner, 1978)
Original Work: "Programming as Theory Building" (1985)

Tell an LLM: "Document the theory behind this code according to Naur — not what it does, but why it is built this way"
Capturing design rationale beyond individual ADRs
Onboarding documentation that explains the mental model behind a system
Justifying time for knowledge transfer, pair programming, and code walkthroughs
Explaining technical debt accumulation when teams change

ADR according to Nygard — complementary: ADRs for individual decisions, Theory Building for overarching understanding
Docs-as-Code — the practice of maintaining this documentation alongside code