Writing readable code

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.