The Cost of Unreadable Code

What differentiates good code from bad is its readability. Is the code easy enough for a new person to read? Can they understand what's going on without too much effort, or do they spend hours dissecting a single endpoint in a CRUD application? Do they need to constantly ask other team members for help because it doesn't make sense?

Writing code is similar to writing a book. The author writes a book for the reader. They have to write so that it is clear and concise for the reader. Not for themselves. There's a strong incentive to make the book readable. If they don't, the book won't sell, putting them out of a job. Similarly, code should be written for the reader as John Ousterhout says in the book, A Philosophy of Software Design.

Code is meant to be read. You'll read the same code tens if not hundreds of times, but you only write it once. So write for readability.

Bad code is often faster to ship, but what are the sacrifices you are making for  short-term gain? It's called technical debt for a reason, and you pay it back with interest.

First, you lose time. Onboarding new team members will take more time than it should with bad code. If the code is readable, the new member can start making contributions early. If it's unreadable, they have to not only spend hours understanding it but also take up valuable time from the team. New changes also require more time. You need to understand the current state of the system and see how to best incorporate your changes. With bad code that takes a lot of time, and adding anything new will only increase complexity.

Second, you spread bad practices through the codebase. In the book Pragmatic Programmer, the authors talk about the broken window theory. It states that visible disorder creates more disorder. Bad code begets bad code.

Consider the case of adding a new endpoint to an existing REST API. You will most likely use an existing endpoint as a reference (side note: you can write a good one from scratch but consistency takes precedence over readability, you want the same kind of bad everywhere). This new endpoint will have all the faults of the old one. If you are new to the field, you have picked up bad practices by working on this.

Code readability is important. The cost of unreadable code is high, but not immediately apparent. Are there times when you have no choice but to ship poor code? Yes, but know the cost you are paying and decide if it is worth it. Most of the time it's not.

Thanks for reading the article. If you enjoyed this and would like to receive similar articles, please consider subscribing. It's free, and I won't ever spam your inbox. Also, consider sharing it with a friend.