<p>I am a developer for over 8 years and a tech enthusiast for over 15 year. Problem solving is my thing, with computers or with with sports like bouldering. I love adventures, from technical ones like trying new technologies till extreme sports like diving.</p>


Vincent Hagen

About me

<p>Programmers often forget that we tends to read more code than we write. But what they forget more often, is how changes affect the mental effort required to understand the code. I refer to this as mental complexity. This mental complexity tend to increase with every addition, it increases tenfold when adding features or adding constraints on some shared context within your application. Even if problems with consistency and concurrence are ignored, shared state is still seen as a bad practice. And I share this view, but not because it is a common source of bugs. Using shared state does not introduce a bug, the bugs are a symptom of something else. The underlying issue all comes down to the strain it puts on your mental model.</p>
<p>While programming you often build up a mental model of everything you need to know and use. For smaller programs everything fits perfectly in your brain and using shared state will not cause much problems (yet). But with every addition this mental model increases, causing all kinds of problems. Developers will start to forget that some things existed, forget to change some shared variable or forget that "no at this stage in the program, you cannot use that variable or it has been changed by something else". The size and the burden of this mental model is determined by multiple factors, on multiple different levels. Let's start by examining how we build this mental model when we try to understand an arbitrary piece of code.</p>
<p>When you try to understand a certain piece of code, you'd often look at specific units like a class, a method or a function. Each of these have their own 'context'. This context is a combination of scope, the state of everything in scope and how this state changes over time. With scope we mean every variable, class and function a certain unit of code uses. The scoping rules mostly depend on the rules of your programming language, but these are consistent throughout your code. In contrast, your state changes all the time. The current function can change local variables, variables outside its local scope or through a reference passed as an argument. All of this would influence the scope of the piece of the your are looking at. Thus also affecting the effort required mental to build this mental model.</p>
<p>Needless to say, the more things are in scope, the bigger the strain on the mental model is. On top of that, the more different calling states it has, the bigger the strain on the mental model. And lastly, the more the state changes throughout the function, the bigger the strain on the mental model. Lets look at a favoured programming concept as an example: Pure functions. Pure functions are functions which are side effect free and their output are a one to one mapping with there input. No state, no side-effects, fully predictable. There scope is reduced to a minimum, it is as big as there input arguments. What is more, they are side-effect free, meaning that they will not cause a state change anywhere else, which further limits the changes we need to track and thus the strain on our mental model. In contrast, global variables have a huge strain on your mental model, because potentially any piece of code in your program can use it and thus it increases the mental strain on every line of code.</p>
<p>But this affects every line of code you change, and with every library you add, most things you add, add to the mental strain. This mental model also ties in really neat with other common good practices! To start with dependency injection instead of a shared container, which reduces the scope of a piece of the. Using smaller interfaces instead of concrete implementation, which limits the scope of all clients of said interface. Keeping your functions smaller, which reduces the size of the context you need to keep in mind. Immutable objects instead of long lived mutable object, which eliminates the change you need to track throughout the objects live time. Thus all these good practices try to reduce the mental strain, which increases the maintainability of your code.</p>
<p>So instead of increasing complexity by carelessly creating new concepts throughout your code. Try to think about what your additions do in terms of mental strain. Try and write code with the smallest scope and context, while reducing side-effects and variable changes. Not because somebody says so, it is called a good practice or it is the cool thing to do. But because this reduces the processing power required to read the code and it will be easier for anybody, new and veteran alike, to join in. Keep an eye out for the mental strain your code produces.</p>


Most programmers know not to keep global or shared state, and when you do, do it so less as possible. But why shouldn't we ? Why is it so bad to use shared state and how does it relate to other constructs such as dependency injection and pure functions.

The mental complexity of code

<p>Developers tend to read more code than they write. Thus every improvement to make our code more readable is a huge bonus for our future selves and our fellow developers. Even more so with open source, where readability is a must, nobody is going to contribute if your code is a complete mess and unreadable. I am not going to say we need to comment more or anything, comments are not the best tool to make your code more readable. You can read more about why I think that in <a href="/blog/2021-02-13-why-comments-dont-make-your-code-more-readable">another blog post</a>.</p>
<p>An important thing is that your programs can tell a story. As Robin C. Martin put's it in his book 'clean code': Master programmers think of systems as stories to be told, not programs to be written. But this doesn't tell us how we do it, so let's start!</p>
<h2>Don't write for yourself</h2>
<p>The first thing to realize is the fact that you should not write code for yourself. The fact that you understand what you did is simply not good enough. Always ask yourself if other contributors will understand the code? And most importantly if far-less experienced coders will understand your code. If so, your future self will most certainly understand the code.
I cannot iterate this enough though. If you assume the readers of your code are really, really stupid. You will be able to understand the code with ease when you take a fresh look at it in the future. So lay off on all your fancy language tricks and one-liners, inexperienced coders don't get that. Don't put personal jokes or references in the codebase, nobody besides you will understand it. So keep it simple.</p>
<h2>Know your tools</h2>
<p>Knowing which tools you have to make your code more readable is half the battle. If you assume you can only add comments, you probabily will end with a lot of readable content, but not with readable code.
My readable code toolbox consists of the following:</p>
<ul>
<li>Naming</li>
<li>Putting code in named functions</li>
<li>Restructuring the code</li>
<li>Refactoring the code</li>
<li>and dead last: explanatory comments</li>
</ul>
<h3>Naming</h3>
<p>First up and most importantly: naming. You probably heard this a lot already, but good names will do a lot for readability. In most languages you can name various things like: Variables, Functions and classes (or/and types). But what are considered good names?</p>
<p>Well, we want to pack as much clear and readable information in all names if possible. So things like <code>i</code> , <code>iX</code>, <code>a</code> or other very small variable names are not good enough. With one exception however. It is very common to use <code>i</code> as a counter in a for loop. This has become so iconic, that this packs so much information in it, that it is fine. Abbreviations should be avoided most of the time since it is hard to read and understand it in code. There are exceptions however common or domain specific abbreviations can be used, everybody should know common abbreviations like HTTP and FTP and typing them out is just silly. But made up abbreviations, for model names or from outside of your domain should never be used, they tend to introduce confusion and these are hard to read for new developers.</p>
<h3>Function</h3>
<p>Next on the list is putting code in named functions. So we developers got this thing, where we can put lines of code that do a certain thing in a function with a handy name we can specify ourself. Use it! I myself actually used to believe that functions were only useful for code reuse. But ohhh boy, you can make some horrible blurry code really readable by putting every few lines in a function.</p>
<p>Take for example the snipped below.</p>
<pre><code class="language-php">public function calculateAndAssignLoyaltyPoints(Order $order): void {
    $this->promotionApplicator->apply($order);

    if ($order->paymentState === 'completed') {
        $this->loyaltyAssigner->assign($order);
    }
}
</code></pre>
<p>In the above code sample the <code>loyaltyAssigner</code>, <code>order</code> and <code>promotionApplicator</code> are part library (so for simplicity lets consider them immutable). The code is pretty small already so what can we do to make this understandable. I know what this does, but without checking the promotionApplicator and loyaltyAssigner you will have a pretty hard time understanding. Let me clarify it a bit.</p>
<pre><code class="language-php">public function calculateAndAssignLoyaltyPoints(Order $order): void {
    $this->calculateAndApplyOrderPromotions($order);

    if ($this->orderIsPaid($order)) {
        $this->assignLoyaltyPointsToCustomerFromOrder($order);
    }
}

private function calculateAndApplyOrderPromotions(Order $oder): void {
    $this->promotionApplicator->apply($order);
}

private function orderIsPaid(Order $order): bool {
    return $order->paymentState === 'completed';
}

private function assignLoyaltyPointsToCustomerFromOrder(Order $order): void {
    $this->loyaltyAssigner->assign($order);
}
</code></pre>
<p>This should be way easier to read. In the new version we even have extra information about what is happening, namely: Assigning loyalty points to a customer. We could rename the <code>loyaltyAssigner</code> to something like a <code>customerLoyaltyAssigner</code> but to me this doesn't make it allot better. I don't want to deviate from the names to much, because the class of the loyaltyAssigner is named LoyaltyAssigner. So naming it similar can be pretty beneficial for readability and understanding the code. One note, if the <code>orderIsPaid</code> can be added to the <code>Order</code> class that would be better, but in this example we assumed <code>Order</code> is immutable for us.</p>
<h3>Restructuring</h3>
<p>Even with all naming correct and clear, a program can still makes no sense because of a wrong structure. Even a good bedtime story will be complete gibberish when you start midway and jump around from chapter to chapter. Generally you'd want to have a structure which tells your story from the start till the end while keeping it simple possible. You can achieve this by trying to explain, in words and without looking at the code, what a function is supposed to do. If the code follows the same story, good job. If not try and restructure it. Can't you tell the story without looking at the code? Your function probably does to much, try and cut it up in smaller functions.</p>
<p>Let look at a small but exaggerated example.</p>
<pre><code class="language-php">/**
 * A user is always allowed if it is an admin
 * For running locally you must be an admin
 * Otherwise check the resource owner against the user
 */
public function allowed(User $user, Resource $resource): bool {
    if ($user->ip !== '127.0.0.1' &#x26;&#x26; $user->role !== 'admin') {
        return $user->id !== $resource->user_id;
    }

    return $user->role === 'admin';
}
</code></pre>
<p>Clearly from the descriptive comment the code is. But it doesn't follow the same narrative? I'd say: yes, we can. Lets restructure the code such that all edge causes are clearly visible.</p>
<pre><code class="language-php">public function allowed(User $user, Resource $resource): bool {
    if ($user->role === 'admin') {
        return true;
    }
    if ($user->ip === '127.0.0.1') {
        return false
    }

    return $user->id !== $resource->user_id;
}
</code></pre>
<p>Now it follows the narrative more closely and we made all edge cases visible, while the 'general' case is at the end. Of course we can go further and introduce some variables to make it even better, but that is besides the point. Another easy way of restructuring code is bringing edge cases more on top and make return clauses simple. This way it is easier to read and explain. Nobody can explain a function whom returns a composition of multiple conditions.</p>
<h3>Refactoring</h3>
<p>Sometimes a minor restructuring or renaming doesn't do much. Or you end up with so many private function which doesn't do the readability justice. In that case you should consider a refactor. Where you split up different parts in separate files / classes or other units. Don't be afraid to introduce a value class of two, it will make it more readable.</p>
<h3>Explanatory Comments</h3>
<p>As a last resort you can add a comment. Why as a last resort? Well every line of comment is a part a non-functional part which you need to maintain besides the code. But don't comment on what the code does, that should be said by the code itself. Tell why it does it. Or with what algorithm. This provides extra context instead of explaining the code in an other language.</p>
<p>As an example, imagine you have a prime number generator based on the Sieve of Eratosthenes. You could explain the whooole algorithm in a comment. But.. Does that do it justice?</p>
<p>What I think is cleaner, write to code as clean as possible, add a comment where you reference the algorithm used and provide a online resource which explains it. This way the code is as clean as possible, and if someone would want to debug / change the code, they have a good enough lead to start gathering information and understanding your code.</p>
<h2>Read; Comment; Rewrite</h2>
<p>So we know what tools we have, but knowing when to use them is not easy. Not to worry, I got a easy starting out strategy. With it you can get a feeling and over time you will start rewriting your code less and less.</p>
<p>Write your code, as you would. Re-reading the code and think what you'd want to clarify or how you would explain it. You can even write it out in a temporary comment if it helps you. Now start rewriting your code with the tools above to incorporate as much of the explanation as possible in you code. Lastly, remove the comment because it is now redundant.</p>
<p>Most of the time it is fairly easy with just some variable renames. But sometimes you will need to restructure the code, put things in private function to clarify the behavior.</p>
<h2>Liked what you read?</h2>
<p>I hope this whole tirade was informational for people, this was my view on writing readable code. There are, of course, many other views on this subject, so don't shy away from reading other people's thoughts. For me books like 'clean code' by Robert C Martin and The Art of Readable Code by Dustin Boswell and Trevor Foucher were a very good resource to get more grip on writing readable code.</p>
<p>Anyway, happy coding!</p>


Have you ever read code from your past self or an open source package and thought "What does this code do?" over and over again? Well you are not alone, but there are things you can do to improve the readability and maintainability without littering the code with pages of documentation comments.

Tips for Readable code

<p>Hi welcome to my website!</p>
<p>I am Vincent Hagen, an enthusiastic senior developer.</p>
<p>Checkout the <a href="/about">about</a> page for more information about me. Or check out any of my <a href="/blog">blogs</a> or <a href="/projects">projects</a> to see what I am currently working on!</p>


home

The website you are reading. Written in NextJS because NuxtJS 2 was becoming outdated while the maintainer hadn't proveded a clear update path from NuxtJS 2 to NuxtJS 3. I already had some experience with NextJS from work projects so translating it was easy enough. 

Littledev.nl

A dutch cooking recipe website for my girlfriend and I. It is Staticly generated with NextJS and it provides a easy way for us to access our cooking recipes. 

Littledev

Latest project

Littledev.nl

Monchou

Latest blogposts

The mental complexity of code

Tips for Readable code