When I started programming, in the virtual dark ages of the eighties, we diligently wrote comments for everything in our code. Over the years, commenting our code has fundamentally changed, and we’ve lost sight of why comments are still a Good Thing.
Comments are snippets of text that you can include with your code. They’re ignored by the compiler, but are meant to help the developer trying to understand and maintain the code in the future. This may be some other poor soul, but it can just as well be the original author, wondering what had caused them to perpetrate this sin upon the software world.
Because we all (hopefully) learn as we go, it usually hurts a bit to see old code from before we became older and wiser.
I was taught to comment my code extensively. We would even make little boxes of comments, carefully typed with asterisks and dashes and often referred to as flower boxes.
Like this:
//********************//
// Author: Lorraine //
// Date: Prev century //
//*******************//
Every method would have a comment explaining what it did. We stated the obvious with wild abandon, happy that we were doing a Good Job.
Then someone came along and said that these comments were not just useless, they were actually misleading. We looked again, and found that after the initial enthusiasm, very few developers kept the comments up to date when the code changed. So the comment said one thing, but the code did something else. Not Good.
Self-explanatory code
Then some more folks (actually some very competent people) came along and said that code should be self-explanatory. That needing comments was an indicator of failure, because it meant that your code needed help to be read.
People like Steve McConnell with his book ‘Code Complete’ and Robert Martin (Dr Bob) with ‘Clean Code’ set out, in great detail, how to write better code. Principles were defined like Single Responsibility Principle (do only one thing in a method), and DRY (Don’t Repeat Yourself) that asked developers to consider re-use and simplicity in code.
These are the cornerstones of good software development, in any language that a developer may work in. There are more principles, which we can talk about another day if you can’t get around to reading the books above.
My point is that we’d done a 180 degree turn on comments. Instead of being proud of leaving some breadcrumbs to help the maintenance programmers navigate your code, we just stopped commenting. It was easier to pretend our code was self-explanatory even if it wasn’t, than leave a comment like a little black mark of failure in a sea of perfection.
I didn’t think I was going to have to say it, but I can hear the noise rising. It’s a chant of irritated developers saying “not all developers…”. I know, I know, and I’m happy you intrepid commenters still exist. Because losing all comments was never the outcome that we should have had.
Real world problems
There are two major reasons why we need to ask developers to re-develop the habit of commenting code.
One is because not all code can be self-explanatory. There may be naming constraints that mean that you can’t change to more meaningful variable or method names, or very complex code that cannot be broken down due to performance issues, or a myriad of real world problems that defeat our best efforts at clean, self-explanatory code.
Two is because there is code that appears very self-explanatory, but has some hidden limitation that will catch out a future developer if they’re not made aware of it. This might be something like making sure that a module is run without admin rights. Seems clear enough, but if a future developer decides to assign admin rights, that will cause the module to behave differently. Sneaky!
My personal rule for comments is to try and eliminate all “how” type comments. The truth of how the method works is most definitely in the code. There is no other truth than the code, and an out-of-date comment is a nasty distraction.
What I miss, and the stuff that causes me to curse developers who leave me blind in the code, are the “why” comments. Explaining why some code is the way it is, really helps. Getting even a glimmer of insight that all is not as it seems, will save me a ton of figuring out from first principles. And it will save my forehead from being banged against the desk in silent protest at having wasted so much time when a line of comment would have put me onto the right track.
So for the sake of my forehead, let’s go back to “why” comments, and remember that enough breadcrumbs will help you to get home safely, and not be eaten by the wicked witch.