Why bother?
Unless you’re a super-human programmer, you’ve written software that contains bugs. Small and obvious ones that were found during your own test runs or more hidden ones that suddenly raised their ugly heads in production. There are entire books and conferences devoted on to how to avoid this.
Besides things in the large (design, architecture, module structure, etc.), there are also a lot of things in the small that can help to avoid or more easily detect problems. Making your code more comprehensible is one of them. It’ll help yourself creating solid code and will be a sight for sore eyes for the maintenance people (yourself?), later on in the product’s life-cycle.
You can shrug about this, but bugs can be very costly. Or worse: deadly. If you wanna have “fun”, read the Wikipedia page about bugs that matter: https://en.wikipedia.org/wiki/List_of_software_bugs. Or this one, that tries to identify the worst software bug in history: https://www.laserfiche.com/ecmblog/whats-worst-software-bug-history/. Or remember the very deadly problems with the Boeing 737 MAX, partly caused by a few lines of code.
Figure 1. The spectacular explosion of the Ariane 5 flight in 1996, caused by a software bug…
 |
Of course we don’t all write rocket, flight guidance, medical or otherwise critical stuff. What we do is usually very… non-critical, ordinary, boring, quotidian? Still, helping yourself and others to easily comprehend what a piece of software is supposed to do is not only just being nice. Some reasons for caring about this:
Whether the software is critical or not, bugs are a nuisance. And understandable code helps detecting them. By others but also, or maybe even foremost, by yourself.
It’s a known fact that most software spends way more time being maintained than initially written. Much of this maintenance time is spent trying to understand what the software is trying to do, and how. Anything we can do to help with this is pure profit.
Software is costly, a few hours spend on comprehensibility upfront saves many, many hours later.
Professional pride…
With my focus here on things we can do during the actual writing of the code, I’m not saying that any measures in the large don’t matter. They do, a lot. But since I spend most of my time in the (XML) software writing trenches, this is what I know most about. And since I encounter a lot of code where things are wrong (yes, also by myself), a little refresher can’t hurt.