Writing readable code

24 / 10 / 2021

Read Time 5 minutes

Define the “WHAT” before the “HOW”

The cost of unreadable code

The way in which code is written can either make it easy or difficult to understand. When looking at code I often wonder, how many hours in total have been spent by developers trying to understand this? what would the cost of those hours add up to?

If it’s difficult to read and understand, making changes will take even longer, further increasing the cost.

If a developer does not quite understand what they are changing they are more likely to break it. The broken code eventually results in a bug and there is often a delay in detecting and then logging it, which means a different developer might work on it. Now a different developer needs to read unclear code that was modified by someone who didn’t quite understand it in the first place…

Think about a complicated, badly written article, which then gets edited by someone who didn’t understand it. Good luck deciphering the original message!

If code cannot be easily understood it is highly likely that it won’t be reused, which means duplication, a code quantity explosion and all the bad things that go with that. If the business requirements are not clearly visible in the code yet the code somehow outputs the correct result, it can become difficult and expensive to respond to change.

Where the code is not readable bugs tend to multiply – often one is fixed and two are created. The cost of a bug can be surprising:

  1. the cost to find it
  2. the cost to document and log it
  3. the cost to allocate or plan resources to fix it
  4. the cost of the developer finding it in the code
  5. then the cost of the developer understanding the code
  6. the cost of the time it takes to write a fix
  7. the cost of the time it takes to move it through the process of releasing
  8. the cost of re-testing it
  9. …lets hope it’s fixed at this point and doesn’t go back to step 3, there is also the lost opportunity and reputational cost

For a company, I would suggest that unreadable code can potentially have a widespread negative impact. As a developer, I feel the unreadable code has the potential to demotivate and hinder progress.

How we often end up with unreadable code

Starting with “HOW”

From what I have experienced code often gets written in the following manner:

  • As soon as the requirement is understood the developer immediately starts with “HOW” to solve it. They might have a pretty good idea or in most cases just a rough idea – either way, pretty soon they start writing code.
  • The code is completely centered around “HOW”. The result is usually very technical and difficult to understand, because in order to achieve the solution there are usually lots of technical and sometimes obscure details.

All too often the result is a heap of mad scientist code that somehow outputs “WHAT” was needed.

We use cookies on our website to give you the most relevant experience by remembering your preferences and repeat visits. By clicking “Accept”, you consent to the use of ALL the cookies.
Privacy Overview

This website uses cookies to improve your experience while you navigate through the website. Out of these, the cookies that are categorized as necessary are stored on your browser as they are essential for the working of basic functionalities of the website. We also use third-party cookies that help us analyze and understand how you use this website.

These cookies will be stored in your browser only with your consent. You also have the option to opt-out of these cookies. But opting out of some of these cookies may affect your browsing experience.


Necessary cookies are absolutely essential for the website to function properly. This category only includes cookies that ensures basic functionalities and security features of the website. These cookies do not store any personal information.


Any cookies that may not be particularly necessary for the website to function and is used specifically to collect user personal data via analytics, ads, other embedded contents are termed as non-necessary cookies. It is mandatory to procure user consent prior to running these cookies on your website.