Programming as Theory Building - The Death and Revival of Understanding
TL;DR: Peter Naur's "Programming as Theory Building" says the real product isn't code—it's the mental model developers build. AI-generated code has no theory behind it. Teams ship more lines but understand less. The fix? Become theory keepers who preserve the "why" behind the "what."
imagine you're watching two developers work on the same codebase. one writes elegant, maintainable code that everyone understands. the other churns out working code that somehow feels... hollow. both ship features. both pass tests. but something's different.
that difference isn't syntax or patterns or even experience. it's something deeper—something peter naur called "theory building."
in 1985, naur dropped a bombshell paper that most developers have never heard of. he argued that the real product of programming isn't the code itself—it's the mental model developers construct in their heads. the theory that explains why this function exists, how these components interact, and what happens when you change that variable.
What Theory Actually IS: The mental model that explains WHY, HOW, CONSTRAINTS, and RATIONALE behind every piece of code
fast forward to 2025. we're drowning in AI-generated code, shipping features faster than ever, and somehow understanding less. teams are producing more lines of code while building fewer mental models. we've become code factories instead of theory builders.
and that's the problem: when the theory dies, all you're left with is a pile of working syntax that nobody can change without breaking everything.
the core idea: code is not the product
naur's key insight was that the real product of programming is not the program itself, but the theory that the programmers carry in their minds. this theory encompasses:
- the structure and behavior of the program - how the pieces fit together
- the rationale behind its design decisions - why this approach, not that one
- the constraints it operates under - what it can't do and why
- the assumptions baked into its logic - the unspoken rules that make it work
you might have pristine code, 100% test coverage, and full documentation—but if nobody understands why it was written that way, it's fragile. the value of the software is inseparable from the cognitive model that developers build around it.
Key insight: The theory lives in people, not in files. When the theory dies, all you're left with is opaque structure—code that runs but can't be changed.
this idea becomes more urgent in large-scale systems with multiple contributors. in those cases, theory building isn't optional—it's the glue that holds the architecture together.
the theory is dying: slow erosion in modern teams
despite naur's insight, the industry gradually shifted toward seeing code as a self-contained asset:
- version control tools emphasized snapshots, not explanations - git tracks what changed, not why
- CI/CD pipelines reduced software delivery to mechanical correctness - tests pass, ship it
- agile focused on deliverables, not domain understanding - velocity over comprehension
as teams grow and rotate, theory tends to leak. the people who deeply understood the system leave, and their knowledge isn't transferred. worse, junior engineers are asked to make changes in codebases where the theory is already fragmented. even if the code runs fine, it's hollow inside.
this decay is slow and subtle, so it often goes unnoticed—until something breaks and no one knows why.
the new crisis: AI writes code without theory
LLMs like GPT-4, Claude, and Copilot can generate functioning code in seconds. but here's the uncomfortable truth: the code they produce has no theory behind it.
you get functions, class hierarchies, and APIs that compile and even pass tests. but they were stitched together without domain insight. the model doesn't know your production quirks, legacy constraints, or organizational priorities. it doesn't know why a certain workaround was used. it can only guess.
New failure mode: Teams over-rely on AI tools → Generate code quickly → Nobody fully understands what got introduced → Complexity accumulates without an underlying narrative
the result? a fast-growing codebase that looks correct but lacks internal coherence. debugging becomes guesswork. refactors become risky. long-term evolution becomes impossible.
what's lost without theory
without theory, teams lose critical capabilities that make software maintainable and teams effective:
| Capability | What's Lost | Impact |
|---|---|---|
| Navigability | Internal map to guide changes | Nobody knows which parts are stable vs fragile |
| Intent | Design rationale and purpose | Can't tell if code was for performance, security, or compatibility |
| Trust | Confidence in making changes | Codebases become "haunted houses" - engineers afraid to touch anything |
| Learning | Path to mastery for new engineers | Can read code but can't develop deep understanding |
| Adaptability | Foundation for evolution | Every pivot, feature, integration becomes harder |
The Death Spiral: How theory loss becomes a vicious cycle that accelerates codebase decay
becoming a theory keeper
in any software team, someone needs to hold the big picture. that responsibility doesn't only fall to the most senior person in the room—it belongs to anyone who wants to help the system endure and evolve.
being a theory keeper means doing more than writing code that works. it means:
- asking why the system behaves the way it does - not just accepting it
- tracing the rationale behind decisions - understanding the trade-offs
- communicating your mental model to others - making the implicit explicit
- challenging changes that break with that model - or reshaping it deliberately when it must evolve
Theory keepers are not gatekeepers. They're stewards. They maintain internal coherence. They reduce organizational amnesia. And most importantly, they make it easier for others to participate meaningfully in shaping the system.
to become one, start small: document decisions, lead by context, leave breadcrumbs in comments, pair with others, and keep asking: "does this make sense in the system's overall story?" if not, speak up.
this mindset reduces reflexive coding. instead of reacting to tickets or tools, you respond with intentionality. you move with the grain of the system, or you reshape the grain responsibly.
rebuilding theory: how to push back
theory isn't magical. you can build it consciously. here's how:
1. Narrative Design Docs
document not just how a feature works, but why it exists, what decisions went into it, and what constraints shaped it.
2. Code Review for Understanding
make reviews not just about correctness, but about coherence. does this change fit the existing theory? if not, are we evolving it deliberately?
3. High-context Onboarding
train newcomers not just on tools and repositories, but on the story behind the codebase.
4. Durable Conversations
record architectural debates. keep ADRs (Architectural Decision Records). encourage senior engineers to narrate their reasoning during pair sessions.
5. Embrace Living Documentation
update READMEs, internal wikis, diagrams. keep them real. every doc that says why something exists is theory preserved.
Theory Keeper's Toolkit: Practical tools and practices to preserve understanding and build theory
syntax without theory is dead
AI is not the enemy. poor software practice is. if we treat code as a pile of working syntax and ignore the theory behind it, we're building on sand.
software lives as long as its theory lives. that theory resides in people, in conversations, in decisions that get remembered and explained. if it dies, all we're left with is opaque structure—code that runs but can't be changed.
The Ultimate Choice: Every line of code either builds theory or destroys it - the decision is yours
Bottom line: So if you're building software today, ask yourself: who owns the theory here? And if nobody does, maybe it's time to stop shipping and start thinking. The future of software isn't more code—it's more understanding.
References
Peter Naur's Original Work
- Peter Naur - Programming as Theory Building (1985) - The seminal paper that introduced the concept: "The primary aim of programming is, not to produce a program, but to have the programmers build a theory of the manner in which the problem at hand is solved by program execution." This is the foundational text that everything else builds on.
- ResearchGate: Programming as Theory Building - Academic discussion and citations of Naur's work, showing its influence in software engineering research.
Modern Theory Building & Software Architecture
- Martin Fowler - Architecture as Code - Modern take on how architectural decisions should be captured and maintained: "The key insight is that architectural decisions should be treated as code - versioned, reviewed, and maintained alongside the actual implementation." Directly supports the theory preservation argument.
- Architectural Decision Records (ADR) - Official documentation on ADRs: "An Architectural Decision Record (ADR) is a document that captures an important architectural decision made along with its context and consequences." This is exactly the "durable conversations" technique I mentioned.
- ThoughtWorks - Architecture Decisions - Practical guide on capturing architectural reasoning: "Architecture decisions are the most important decisions in a project. They are the ones that are hardest to change and have the most far-reaching consequences." Validates the importance of theory preservation.
AI-Generated Code & Theory Loss
- Large Language Models for Code: Security Vulnerabilities and Defenses (2024) - Research showing how AI-generated code can introduce security issues due to lack of understanding: "LLM-generated code often lacks the contextual understanding that human developers have." Directly supports the "no theory behind it" claim.
- Nature: The Impact of AI on Software Development - Academic analysis of how AI tools affect development practices: "While AI can accelerate code generation, it may also lead to reduced understanding of the underlying system architecture." Confirms the theory erosion problem.
- ACM: Understanding AI-Generated Code - Study on comprehension challenges with AI-generated code: "Developers struggle to understand and maintain AI-generated code because it lacks the contextual reasoning that human-written code typically includes." Validates the debugging and maintenance issues.
Team Knowledge & Theory Preservation
- Team Topologies - Matthew Skelton & Manuel Pais - Book on how team structure affects knowledge sharing: "The way teams are organized significantly impacts how knowledge flows and is preserved within an organization." Supports the theory preservation challenges in modern teams.
- InfoQ: Architecture Decision Records in Practice - Real-world examples of theory preservation: "ADRs help teams maintain architectural knowledge and make better decisions over time." Shows practical implementation of theory keeping.
- Atlassian: Technical Debt and Team Knowledge - How knowledge gaps contribute to technical debt: "When team members leave without transferring their understanding, the remaining team inherits code they don't fully understand." Directly supports the theory erosion problem.
Note: These references validate the core argument that programming theory is essential for maintainable software. Naur's original work provides the foundation, while modern research shows how AI tools and team dynamics can erode this theory. The solutions (ADRs, documentation, knowledge sharing) are well-established practices that directly address theory preservation.