Why Peter Naur’s Programming as Theory Building Still Matters

When I first opened Peter Naur’s essay Programming as Theory Building I had the same reaction many developers have when they finally encounter a classic that never showed up in a university syllabus: “Why didn’t anyone tell me about this?” The piece is short, but it forces a shift in perspective that makes a lot of the usual advice on clean code, architecture, and testing line up in a coherent way.

---

What the essay claims

Naur argues that the primary artifact of programming is not the source file, not the test suite, not the UML diagram. Those are all secondary – they exist to support a larger goal: building and communicating a theory of the program. By “theory” he means a mental model that captures the requirements, the design decisions, and the relationships between parts of the system and the surrounding domain.

In practice this means a programmer’s job is to learn, refine, and share that model. Everything else – naming conventions, refactoring, documentation, automated tests – is a tool for making the theory clearer to oneself and to others.

---

What is actually new?

The novelty is not a new language feature or a fresh metric. The novelty is a meta‑level framing that unifies many disparate activities that developers treat as separate chores:

Traditional activity	Typical goal	How it fits the “theory” view
Writing clean code	Reduce cognitive load	Makes the mental model explicit in the code itself
Designing architecture	Organize responsibilities	Provides a scaffold for the overall theory
Adding documentation	Explain intent	Externalizes the model for future readers
Drawing diagrams	Visualize structure	Gives a high‑level map of the theory
Writing tests	Guard against regression	Encodes expectations that are part of the model

When you see all of these as communication channels for the same underlying theory, the trade‑offs become clearer. For example, a heavily documented module that is also heavily tested is not redundant; each artifact reinforces a different slice of the same mental model.

---

Why the framing helps solve “why is good software hard?”

Good software is hard because maintaining a consistent theory across a team and over time is difficult. Code rot, knowledge loss, and accidental design drift happen when the theory is only partially captured or when the communication channels diverge.

Consider a typical scenario: a developer needs to add a feature but cannot locate the relevant design rationale. Without a shared theory, they either:

1. Guess based on the current code (high risk of hacky patches), or
2. Spend a lot of time reconstructing the rationale from commit messages, tests, and ad‑hoc comments (low productivity).

If the team had treated the codebase as a living theory – with regular refactoring, design‑pattern documentation, and purposeful tests – the mental model would be explicit, making the change straightforward.

---

Practical takeaways

1. Make theory explicit early – When starting a new component, write a short “theory statement” that describes the problem, the core invariants, and the high‑level design. Treat it like a lightweight design document.
2. Treat artifacts as redundant views – If you add a test that checks a business rule, also update the corresponding comment or diagram. Redundancy is intentional; it reduces the chance that one view becomes stale.
3. Use patterns as language – Design patterns and Domain‑Driven Design (DDD) vocabularies are essentially theory‑building tools. When you name a module a “Repository” or a “Factory”, you are communicating a piece of the mental model to anyone who knows the pattern.
4. Schedule theory‑maintenance – Just as you have a sprint for bug fixes, allocate time for “theory hygiene”: update docs, prune dead code, and revise tests that no longer express the intended invariants.
5. Encourage shared mental models – Pair programming, code walkthroughs, and architecture review meetings are not just about catching bugs; they are about aligning everyone’s theory of the system.

---

Limitations of the approach

• Over‑documentation risk – If every tiny decision is recorded, the theory becomes noisy. The key is to capture principles and invariants, not every implementation detail.
• Team discipline required – The model only stays useful if the team consistently updates it. In fast‑moving startups, the overhead can feel burdensome unless the benefits are made visible.
• Tooling gaps – Most IDEs treat code, tests, and docs as separate entities. Integrated views that surface the shared theory are still an open research area.

---

Connecting the dots: patterns, DDD, and intellectual control

Naur’s essay predates modern terminology, but his “theory” maps neatly onto concepts like Intellectual Control (the ability to reason about a program’s behavior) and Domain‑Driven Design (explicitly modeling the domain as a shared language). Design patterns, from Singleton to Strategy, are simply named fragments of theory that help teams communicate intent without re‑explaining the underlying reasoning each time.

---

Final thoughts

Reading Programming as Theory Building does not give you a new framework or a checklist; it gives you a lens. When you look at clean code, tests, and diagrams through that lens, they stop feeling like unrelated chores and start feeling like coordinated efforts to keep a shared mental model alive.

If you haven’t read the original essay, it’s short enough to finish in an hour and still manages to shift how you think about everyday programming work. The next time you write a comment, add a test, or sketch a diagram, ask yourself: Which part of the program’s theory am I trying to communicate here? That question alone can make the activity more purposeful.

---

The original essay is available through several university libraries and open‑access archives. A quick search for “Peter Naur Programming as Theory Building PDF” should surface a copy you can read legally.