Keep IT clean — coding good practices: comments
I would like this post to launch a series of articles about good programming practices. I was inspired by Robert C. Martin’s “Clean Code: A Handbook of Agile Software Craftsmanship”, which I highly recommend to anyone who hasn’t dealt with it yet. The subject of comments goes for the first shot. Enjoy your reading.
Comments. It’s commonly said that good code doesn’t need them. Everyone should agree wholeheartedly with this thesis and stick to it. Of course, there are exceptions that I’ll tell you about, but in most cases, comments are bad mainly because the use of them means that we wrote a code that could have been better written. Also, instead of adding a comment that explains the incomprehensibly written code, let’s take better to correct it.
Good comments
At first, let’s start with these. There will only a few examples, because most of them landed below the “Bad comments” headline. Despite that, adding a comment is sometimes a must or just a good idea.
// TODO
They are notes left by the programmer in a particular reason. He writes it when he thinks that something should be added, changed or deleted and when that couldn’t be done at the time of writing this note. It can be a reminder, a request or a proposition, e.g. of thinking about a better name for a written method that we don’t quite like. Below is an example of //TODO as a reminder about removing lowerCase()whenEmailNotification is ready.
Of course, keep in mind that the //TODO comment can never be an excuse for not finishing or writing the code carelessly. You must also keep an eye on them and not forget about their existence.
Warnings
Sometimes writing a warning is a good idea. If the use of our code in some extraordinary situations will involve e.g. a decrease in performance of the program, it’s worth leaving a line of commentary informing other developers about it. Like here:
You can say that there’s something wrong with this code if there’s such a risk. This is, of course, true, although things happen. In addition, since this code has been created and at the moment there is no possibility of correcting it, this warning can save other programmer’s time and nerves.
Strengthening the importance
Occasionally, excuses can find these comments which indicate the importance of some line of code or the execution of a certain operation occurrence. Of course, you should always justify why what we point at is really so important. Let’s look at the example below. It’s written in Java again and it has a comment that explains why remembering to close the sender is critical:
Bad comments
As I said before comments are in general a bad idea and their existence means that our code isn’t good enough. Here are some examples of what you shouldn’t do.
Mumbling
First of all, there are some comments that their usage could be rational, but the way of how they’re written is only making the reader more confused. A programmer who has to deal with our code with such a comment has a difficult task. Regardless of whether he only needs to use our method or make a refactor, he won’t start working without understanding our commentary. So if it’s written in a vague way, we make it harder for him to work. He must devote his time to understanding. Moreover, what if he misunderstands? This may affect the quality of his code due to misinterpretation. Look at this example of mumbling:
In the above example, we don’t know what the programmer meant and what reasons did he have to put this code in the catch block. If the charge variable is null then the calculateGrossPrice method will throw an Exception or will it calculate the price using the default charge? If the first one, then when will this price be calculated? Maybe it has already been calculated somewhere before calling this method, or maybe we have to do it ourselves? As you can see, this type of comment can make it difficult so much.
Repeated comments
Sometimes I come across some absolutely unnecessary comments, because they could be replaced by a well-written code without a problem. It gets even worse when such comments are repeated. Below is an example of a domain class, which has well-described fields and so many unnecessary comments that look very similar. They’re explaining what’s already visible thanks to correctly named fields and a context.
Unnecessary comments
It’s equally common to write bad code in terms of naming variables and methods and rescuing its intelligibility by adding comments. It’s really worth spending some time thinking about nomenclature than wasting bits on unnecessary comments that obscure the code. In addition, what if the comment is removed by someone, and the name of, for example, the method, will not be refreshed? Houston we have a problem.
Take a look at the example above. Almost identical code has already appeared here. The only difference is the name of the method. The name create forced the developer to write a comment explaining what this method does, although you can actually deduce from parameters, body and what it returns. This comment is certainly unnecessary, all you have to do is to name this method e.g. createLogsFile.
Commented code
One of the worst things is leaving the commented code. It’s very unprofessional. The author of the commented code knows why he left it, but no other programmer who comes across this code will have the courage to remove it for a simple reason — how should he know for what purpose this code is commented and left alone? Maybe it was left here for a purpose and it’s too important to be removed like this one:
To sum up, remember that comments should be avoided and used only in specific cases like //TODOs, warnings or strengthening the importance of our block of code. If your code requires frequent comments, it means it could be better written. Software that we make will be much better if we use comments more carefully. By writing “better” I mean that its code will be much more accessible and understandable for us after some time and for other developers. This fact implies that the final quality of the software for the end-user will be much higher, because it will be a pleasure for developers to work with a nice code that has as few comments as possible, so they could show off their programming skills rather than spending much time understanding someone’s comments.
That’s all. I have presented examples of both bad and good application of comments in our code. I remind you that I was inspired by Robert C. Martin’s Clean Code: A Handbook of Agile Software Craftsmanship. So if you want to read more about the comments and in general about the clean code, I encourage you to buy it.
