Comments are important but don’t forget that your code should also be self-commenting.
If I had to sum this episode into a single sentence, I’d have to say that comments should explain why some code is not obvious. And this is after you’ve done everything you can to make the code obvious in the first place.
If you find yourself writing a method called getName and then adding a comment that says, “This method returns the name,” then your really might want to reconsider the need for that comment. And going the other way, if you find yourself writing a method called performWork and then adding a comment that says, “This method calculates the average value of the input stream of numbers,” then you might want to just rename the method to calculateAverageValue instead.
In both of these examples, instead of either making the comment redundant or relying on the comment to explain what the method really does, it’s much better to just let the code document itself. Choose descriptive names for your methods, class names, and variable names.
When you’re designing software, one guideline that will help you keep your design understandable is to limit the scope of what a class or method does.
If you’re having trouble coming up with a method name and the best you can think of is performWork, then maybe that’s because the method is trying to do too much. It’s a clue that if you’re thinking about something as just a mass of work, then it could probably be divided into smaller and more descriptive methods. And if you do try to use descriptive names and find yourself with a method called readDataAndCalculateAverageCheckWinningMove, then it should be obvious that method is trying to do too much.
Listen to the full episode for more including a couple common mistakes that developers sometimes make with comments. You can also read the full transcript of the episode below.
Transcript
“Blank line added for readability” I still remember that comment from an old issue of the Microsoft Systems Journal magazine. That was back before it was renamed to MSDN. It was a funny article I think from an editor about how people can go too far with comments.
If I had to sum this episode into a single sentence, I’d have to say that comments should explain why some code is not obvious. And this is after you’ve done everything you can to make the code obvious in the first place.
I’m not saying that you should never use comments, far from it. Because there will definitely be places in your code where, for example, you could have used any of several different designs. Adding a comment that explains why you chose a particular design is great.
I’ve worked for companies before that insisted that every method needed a whole block of comments to document the method name, it’s purpose, each parameter type and meaning, the return value type and meaning, any exceptions, related methods, and all done so in a way that documentation could be printed.
I’m not a big fan of using comments for this. Unless there’s a valid reason. Had the code been for a library that other developers would be using and the documentation turned into an online resource, then maybe. But that wasn’t the case.
If you find yourself writing a method called getName and then adding a comment that says, “This method returns the name.”, then your really might want to reconsider the need for that comment.
And going the other way, if you find yourself writing a method called performWork and then adding a comment that says, “This method calculates the average value of the input stream of numbers.”, then you might want to just rename the method to calculateAverageValue instead.
In both of these examples, instead of either making the comment redundant or relying on the comment to explain what the method really does, it’s much better to just let the code document itself. Choose descriptive names for your methods, class names, and variable names.
Descriptive names have an added benefit that I’ll explain right after this message from our sponsor.
When you’re designing software, one guideline that will help you keep your design understandable is to limit the scope of what a class or method does.
If you’re having trouble coming up with a method name and the best you can think of is performWork, then maybe that’s because the method is trying to do too much. This is not always the case and I’ll get to that in just a moment. But it’s a clue that if you’re thinking about something as just a mass of work, then it could probably be divided into smaller and more descriptive methods.
Methods that comment themselves.
And if you do try to use descriptive names and find yourself with a method called readDataAndCalculateAverageCheckWinningMove, then it should be obvious that method is trying to do too much.
But what about main? Doesn’t everything eventually have to fit inside the main method? Yes, it does. But that doesn’t mean that method has to do everything itself.
If you’re building a game, then create an instance of your game object and call a method to play the game. If you want to get fancy, then the main method might also prompt the user to play again. But that’s about it.
Maybe you’re not building a game. Maybe you’re building a utility app or a paint-by-numbers coloring app. It doesn’t matter. Keep your entry method small by transferring control to some other code that is more focused.
Now, one place where you might run into problems is when working with base classes, or composite structures, or anything really that names methods to be implemented later by other code. The structure might already be determined for you leaving little room to refactor into more focused classes and methods.
Sometimes the right answer is to go back to the existing code and make changes there. You might be trying to use that code for things that the original developers never thought about or intended. Or maybe some new design has become popular that didn’t exist before.
Take almost any application that works with documents for example. A long time ago, it was normal to work on a single document at a time. And if some application was written to do this, then it makes sense that application would have internal designs that could only work with one document at a time.
If you need to add the ability to work with multiple documents, then you’ll probably end up changing a lot of fundamental code. Or maybe you need to update to a new application library or framework if the original code used such a thing.
The point is that the code will need to change. Don’t try to just change the internals of a class or method and think that a comment or two will be enough to explain what happened.
If you need to change your code a little or a lot, remember to keep it focused and self-documenting as much as possible. Then use comments to describe insights into the code that aren’t immediately obvious.
Before I end, there’s two final misuses of comments I’d like to talk about.
◦ #1 You might find comments being used to keep track of work that still needs to be done. Don’t add a comment saying that something might not work or still needs to handle some situation or another. Use an issue tracking software or something outside of the code to keep track of things like this. Comments have a way of getting buried in the code and not being read again until some developer needs to fix a bug. Maybe the bug the comment originally warned about.
◦ And #2 You might also find comments with a developer name and date and maybe a bug tracking number. Or worse yet, a comment section at the top of a file intended to hold a history of changes made to a file. all I can say is, “Don’t do this.” Use the proper tool for the job. And this means you and your team really should be using a version control system. Just like the issue tracking system, a version control system gets these details out of the code. Let your version control system keep track of the history of your source files. You’ll find it to be much more reliable too.