Skip to main content

Code as Knowledge

programming
flow
technicalDebt
Code Is The Truth - so how can we reconcile the as-built truth to the as-desired specification? Let’s start here…
Published

November 15, 2026

How is Source Code the Truth?

Code is the truth

I’ve often repeated that line. I credit it to Ron Jeffries, though the very first use may be lost to time. I’ve heard it also from Bob Martin who was one of my key tech mentors in the late 1990s and early 2000s.

When I mention it in social media, I’m often greeted with “helpful corrections” by various people, who usually are strangers to me. They tell me that the real truth is not in the code, but in the documents, or the heads of subject matter experts, or some other place.

I think we need to understand first that there is a big difference between “being true” and “being right.”

The point here isn’t that code is perfect, and does all the right things, but rather that code is all that goes to the CPU of the computer(s).

It is not accompanied by the expert’s opinion, the documentation, or the best intentions of the engineers1.

For illustration, imagine there is a defect in the code. At runtime, it is observed doing the wrong thing. While it may disappoint experts, designers, and probably even the programmer, at runtime that misbehavior actually happened. It is objectively true.

In this sense, the code is truth and the specifications are the intentions. The specifications may even be right but the code is true.

When our expectation differs from reality, remember that reality is what really happened.

It doesn’t do us any good to argue that reality is not real, but we can argue that it’s not right.

Making a reality that fits our expectations as well as possible is what engineers of all sorts do for a living. It eventually comes down to physics.

Why does this matter?

There have been many attempts to treat documentation as the singular authority in projects, and code as a mere projection of the documentation. Some texts refer to programming as “translating the requirements into a programming language.” The documents-as-authority opinion is held primarily by the people writing the documents, especially those who don’t have to “get their hands dirty” in the work of making it actually run on a computer.

The docs are probably right. I won’t say differently, but they’re not truth yet. In fact, the documents have no use and no market fit and potentially no value until they become source code and are eventually used by customers to do the customer’s work. Until then they are informed ideas, disembodied ideas.

That doesn’t make them wrong. Let me reinforce that. It’s just that they’re not truth yet, and their value is expected and not yet proven.

So far all of these attempts to make documentation the authoritative truth have struggled and failed, because there are certain issues with documentation that are innate. The discipline from all actors to reconcile the documents and code in all aspects across many revisions is just not available from humans, even augmented with computer programs and LLM agents.

The intention is right, though. You do need an accessible, relevant, meaningful expression of the system. You do need a coherent “view” of what it does, and what it should do.

If you read Peter Naur’s “Programming as Theory Building” you will see his definition of a “live” program is that where the theory of how and why it works is still present in the head(s) of the developer(s). When that theory is lost, the program is “dead” until the theory is painstakingly recreated (if ever).

This makes some document-focused people feel that the answer is to document the entire theory so that we have all the information that matters all of the time, but at that point we need a more precise language to write the docs in and a more automated way of checking it – in essence, a computer programming language.

Any document with sufficient detail to accurately describe a program is the program, and requires programming skill to properly create.

And, FWIW, the evolution of programming languages for decades has been to clearer, cleaner, and higher-level description and frameworks for describing behavior quickly, neatly, and consistently. We already had that before AI became a thing.

But AI is like a compiler and loves long, detailed documents!

Sadly, no.

It is not like a compiler. It is like an LLM, and while it can definitely produce good code, it’s not built to deterministically turn inputs into outputs. That’s not what they’re for, and it’s not how they work.

Big, detailed documents are a problem for them. They only have so much context available. They are prone to “context rot”, distraction, structural parsing issues, high noise:signal ratio, tokenization issues, and variations due to their training set.

The only things that are like compilers are compilers: deterministic input-to-output converters. LLMs are a newer (to us) and different technology. If we wanted compilers, we already had those.

How do we resolve document vs code?

They are different. Let’s go with that, and accept that documentation is correct in the moment, in some respects, and that the code is a different corpus that may have differences.

If you can, imagine that an “as-built” document is an ephemeral projection of the code, produced on demand. It is faithful to the implementation at this revision, since it is read from the code on your desktop in your working directory or branch at the moment.

That projection is truthful about the implementation, including behavior nobody intended.

The “as desired” is a user story, feature specification, or just a few sentences that describe an idea.

That as-built document is more easily comparable to an as-desired document than the raw code artifacts, whether this is done by a person, an agent, or both.2

To do that, we need the code to have a particular set of qualities that make it easy to collect and assess it, and thereby produce a projection that is accurate (enough) and complete (enough) that we can make reliable changes.

So, the job is to understand the choices and consequences of a change before choosing to make it.

So what’s in the code?

  • IaC - infrastructure declarations are key to seeing architecture
  • Production code - the actual instructions themselves
  • History - the version control record of how code is maintained and evolved
  • Tests - current code behavior made real and provable
  • Structure - the hierarchies, modules, and patterns of the system
  • Scanner results - type checkers, error scanners, security scans, etc

That leaves us two problems for projecting a document:

  1. How to make it more extractable
  2. How to extract it

Connect evidence to representation-refactoring review.

If we can pull this off with the use of agents and deterministic tools and magic beans and infinite genie wishes, it will be the biggest step-up we’ve seen since the invention of high-level languages.

If we can’t, well, we’ll have to wait for some other cool breakthrough in the future.

Many of my blogs that follow will describe my efforts in this endeavor, including some failures and missteps, to be sure.

Footnotes

  1. Admittedly, it goes through compilers, optimizers, JITters, virtual machines, microcode that slices it into pipelines and concurrent pieces and such, but it is essentially the code and certainly not those other things I mentioned.↩︎

  2. My preference is “both”: the “centaur developer”↩︎