The first rule taught in software development is, “Comment your code with a reason or purpose for its existence.” This is to say, “Why does this variable, method, or class exist?”
Here’s why.
Heavily used code always suffers from purpose creep. Purpose creep leads to expensive bugs. For example, I once found a bug in code used by hundreds of corporate customers that consisted of a variable being used for two purposes. Most of the time, the variable value was the same value for both purposes. However, after selling the software for many millions of dollars to 100’s of clients that expected to never change their integrations with our code, we had a problem that required new installations and new integrations.
Talk about a preventable problem. One comment explaining the purpose of one variable could have saved the company millions of dollars worth of angry customers.
To prevent purpose creep within a class, method, or variable, stick with the purpose described in the comment, or change the comment. It’s very easy for a maintainer of old code to assume the purpose of a well named variable, but not realize the actual purpose is similar, but not the same as he thinks it is.
The first rule of programming that is thrown out the door in the workplace is, “Comment your code.” Even at the better companies I’ve worked for, almost no one comments their code. Some developers live in a fantasy world where class names, method names and variable names give all the architectural details needed to understand millions of lines of code. I once ran into a 45,000 line class with no comments. I even worked for a company that forbade comments, and you could get called in for a talk with your manager if you made the mistake of leaving a comment in your code–very Dilbertesque.
Every codebase has blocks of code that are so important that they are called constantly. And when an edge case is found, those blocks of code get a conditional thrown in to handle that edge case. Then another edge case is found and a new parameter is passed in to handle that edge case. Another developer under tight deadlines realizes the code is perfect except, it needs to handle his case where ….
As a result, almost every important method and class suffers quickly from purpose creep. By this I mean that if you found someone that actually understands the class or method in question, it will take minutes and sometimes hours for them to describe what is going on in the class or method.
Soon, the most important code in your application is too fragile to change. Ten or twenty edge cases that no one remembers have infiltrated your most important code. And worse yet, there are no comments explaining what can brake if even a minor change happens to your code. Then a maintainer of the code gets stuck working nights and weekends making changes to once simple software.
Detailed commenting of important code helps prevent fragile code. Have a concise explanation of purpose of your code. If the comments are getting hard to follow, then it is time to refactor the code into easily described chunks. Maybe move those edge cases out into their own methods or classes.
Comments containing clear purpose statements can prevent working late nights, lost customers, and even save your company millions of dollars. There’s a lot to be said about the lowly comment.