> ## Content Index
> Fetch the complete content index at: https://decomplecting.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# Reality in code
- URL: https://decomplecting.com/blog/reality-in-code/
- Published: 2026-10-06T21:28:40.000Z
- Updated: 2026-10-13T09:21:42.000Z
- Author: Ramin Soltanzadeh

> It may surprise you to hear this, but I don't believe that code is primarily a set of instructions for the computer. Actually, I think the fact that code instructs the computer is almost a happy accident.  
>  
> I believe very deeply that the vastly more important role of code is as a means of communication with other human beings.

— Kyle Simpson, Functional-Light JavaScript

## Introduction

Placing a high value on the readability of code should be uncontroversial. Most would agree on this, but disagree on what it means for code to be readable.

To me, readability consists of two orthogonal qualities.

#### Parsability

The following two snippets differ in their parsability but are just as easy to understand once parsed.

```javascript
if(a!=b){for(let c in d){foo(c)}}
```

```javascript
if (a != b) {
  for (let c in d) {
    foo(c)
  }
}
```

Subjectivity matters little here. One is overwhelmingly better than the other, and objectively so. This is obvious and relatively uninteresting despite getting more than its fair share of attention in various coding guidelines.

#### Understandability

This is the interesting one. Objectivity is vastly underrated here. Familiarity with a certain style of code does make it subjectively easier to read, but that is far from the whole story. Familiarity comes easily and quickly; it is worth very little even though we tend to let ourselves be driven by it.

Disregarding familiarity, what makes a piece of code easier to understand than another? 

## Understanding the problem

We write code to solve a problem. The quality of our code has an upper limit: our understanding of the problem. We cannot write better code than that.

The solution starts with understanding the domain. The next step is writing code, by which time the upper limit has been set. As authors of code, we therefore have two goals:

- Deepen our understanding of the domain, increasing the upper limit of our code quality.
- Write code that resembles the description of the domain as closely as possible.

In hindsight, it seems obvious. If we can articulate the problem well, and we write code in a manner that is similar, our code will be easy to read.

## Mimicking reality

Lately, "natural language programming" and "spec-driven development" have been all the rage. In all the wrong ways, of course: lazy and nondeterministic code generation with utter disregard for the problem domain.

While currently associated with madness, writing code in a way that is close to natural language and the domain specifications is precisely what we want. By mimicking reality with disciplined coding practices, we do just that. Let us look at some examples.

#### Declarative coding

We are given the task of finding the name of the oldest person in a list of people. We come up with two different ways of solving it.

```csharp
string GetOldestPersonName(IEnumerable<Person> allPersons) 
{
    var currentMaxAge = allPersons.First().Age;
    var currentPersonName = "";
    
    foreach(var person in allPersons) 
    {
        if(person.Age > currentMaxAge) 
        {
            currentPersonName = person.Name;  
        }
    }
    return currentPersonName;
}
```

Imperative C#

```csharp
string GetOldestPersonName(IEnumerable<Person> allPersons) 
{
    return allPersons
        .OrderByDescending(p => p.Age)
        .Select(p => p.Name)
        .First();
}
```

Declarative C#

One of these reads much closer to how the problem is stated in natural language, and that version of the code is much more readable. 

In fact, there is a bug in the imperative version. Did you spot it? Will the next person spot it? Notice how little surface area there is to introduce a bug in the declarative version.

This is a typical example of what you would find in an introduction to functional programming. This is good, but there is more.

#### Data modelling

When modelling our data, we often do it in a way that does not correspond to reality at all, but with the illusion that it does. The illusion is strong; this is a difficult hole to climb out of.

Consider a to-do app, where users can log in, create to-do lists, follow other users, and edit their profile. Notice how easy that was to describe. Each feature is a separate concept that required no coordination to specify. Reality is *simple*.

In code, we often find data models like the following.

```typescript
type User = {
  id: string;
  email: string;
  sessionToken?: string;
  displayName: string;
  bio?: string;
  avatarUrl?: string;
  todoLists: {
    id: string;
    title: string;
    items: { text: string; done: boolean }[];
  }[];
  followers: User[];
  following: User[];
  followerCount: number;
};
```

ℹ️

This is a small example. In practice, data models are often much larger as they grow indefinitely over time.

This is a disaster. Everything has been [*complected*](https://decomplecting.com/blog/about/). This does not reflect how a user would be described. This is certainly not what a user *is*. Login data and follower data would never need to be considered together. This does not mimic reality!

Even though we have already established that we should seek to represent reality as closely as possible, it is probably not clear why this is a big problem.

This "god object" exists because of the way the author thinks. This way of thinking will continue. The different parts of the code—the would-be modules—will revolve around this god object (and other god objects) rather than being built freely and independently. The whole system will be a mess of complected spaghetti instead of a *composition* of independent modules.