I’ll often find myself muttering that the code I am having to fix lacks documentation. I can’t figure out what does what – it’s overly complex. To boot, it’s probably unreadable.
I take away from this experience that I should write more readable code. That I should write documentation, and keep things from getting too complex. But this may actually be a confirmation bias causing me to make the wrong decisions, or at best, a case of correlation does not equal causation.
What happened here was something broke, and I had to go into that code and fix what broke. When I get into the broken code, I find it poorly documented, hard to read, and overly complex. Since I don’t want to feel those pains in the future, I resolve to change my behaviors so that the next time something breaks, it’s easier for me to debug.
The next time something breaks…
Instead of focusing on writing code that’s well documented, simple and readable, why don’t I instead focus first and foremost on code that doesn’t break in the first place? No one complains about the code they don’t have to fix, no matter how unreadable, complex or poorly documented it is.
Indeed, if I adopt the habits of readable code, simple designs, and thorough documentation and find my life getting better, it’s far more likely that those practices didn’t just make debugging easier, they made debugging more rare. Code built with those habits tends to be less defect prone in the first place.
The amount of effort we put into our designs is not limitless, and ultimately, time spent doing one thing can often cost us time spent doing another thing. Some practices, like writing readable code, are relatively cheap whereas others, like effusive documentation, can be expensive.
It often makes more sense to spend time you might have spent documenting on making the thing you’re documenting less error prone to begin with. If it never breaks, the documents you slave over may never get read. Likewise, if a certain software technique – such as functional programming in a strictly procedural shop – gets your work flagged as unreadable, it may still be worth it due to the lower defect density.
No comments yet.