Code comments: timesavers or the impeding little buggers

In computer programming comments have their own specific purpose for being used. They considered to be the explanations to a written code of a particular program. Concerning their necessity the opinions highly differ. Some are deadset that if the code needs additional explanatory commentaries then it’s too complex and should be re-written. At the same time, others consider comments to be useful and timesaving information that helps faster and easier to understand the code intent. But there are always two sides to a coin. As easily as comments can help they can confuse and distract. So, in this article we’ll be talking about how important or not are the code comments and when it’s appropriate to use them.

Should we rely on comments?

The thought that I believe to be very true is that while writing a code from the very beginning you should make it as simple as possible, and only at the point when it’s no longer doable you should add commentaries. For me the best code is an exceptionally expressive code, the one that talks for itself. And it’s better to write the piece of code differently to make it more expressive rather than to leave a lot of additional comments. But every rule has its exceptions. What I also believe to be true is that no code, simple or not, can be completely self-documented. There are times when adding comments is a considerable thing to do.

What do I mean by that. Sometimes the things that are absolutely clear and obvious to one developer might be utterly incomprehensible to the other who has no context. Of course, code should be written with the readers in mind, but there are cases when it might not be possible. An even thou we should not fully rely on the additional explanations, we have to know what types of comments are appropriate and have their right to be.

Code — how, comments — why

If to archive some goal, whether it’s better performance or something else, you had to write a clever, not too transparent code, then commenting on it is probably a good idea. Same goes for times when you’re fixing a bug in somebody else’s code, especially if this code is an unclear one. And after you finally figured it out struggling for a certain period of time, rewriting a whole thing might be a hell of a work and very time consuming. Let alone doing it all the time for every unclear code where you’re fixing something. It’s crazy! But leaving a comment takes only a few minutes and can save a lot of time and trouble for the next developer working with it.

So, commenting a code make sense, but you should consider what do you put in your comments. They don’t have to repeat what is already obvious. Code itself tells how it does its work, but why the code is where it is and what it does there — these what might need explaining. As I’ve said before, as easily as comments can help they can confuse and distract. Putting comments that simply repeat what the code says itself only interrupts the focus of a person who reads it and might be really annoying. But providing information in your comments that is hard to get from the code — that is valuable. For example, by telling with which aspects of a program a big source file deals with you’re providing a valuable information obtaining which could’ve taken much longer for the other programmer.

False comments

Code maintainers don’t often keep the comments in line with a code and these might result in last getting out of sync with the code and misinform. And what information could be worse than the wrong information.

Whether to completely avoid this happening might be hard to do, to reduce the possibility is manageable. With this purpose try to keep the comments close to the compliant code. Usually the comments are being skipped and not updated because we don’t pay attention to them. Also add comments at the beginning of a file, its subject, a place that doesn’t change often, as opposed to the implementation of a file.

A good idea is to comment at the level of intent. While the implementation of the intent can change very often, the intent itself might stay for a long period of time. The way to do it is to use comments in a form of pseudocode to outline intention. Thus you’re explaining the logic behind the code, what it intends to do and not how it implements it.

The other level of intent that the code itself doesn’t actually express well is why it implements this way and not the other. So, this might be a valuable information for the maintainers of a code. If you’ve tried a different design or a different way of implementing this code and it didn’t work out, including it in your comments (what you did and what was the result, why it didn’t work) might help a great deal.

Comment or not to comment, what is a conclusion?

You see that, looking from one side, comments can be a great tool to improve your code, and judging from the other — they can be misused and only do more damage. So it comes down to your own personal preference and judgement. In my opinion, if there’s a way to make a code more clear and expressive, then do so, if for some reason it’s not possible or not even up to you, then comment on it. And do it in a way to actually make it easier to understand what the code does and why it does it this way. Imagine that you’re saying what the code can’t to a man next to you. In any case, it’s better to leave a useful comment on an unclear code than to leave the other person reading this code and going: “What the f…?”.

P.S. So, we’ve reviewed two sides of comments being a good or a bad thing for the code and those who read it. In CheckiO we certainly believe that explanatory commentaries can be very useful for educational purposes and might really help other people to learn how to code. Many of our users leave their solutions of the various interesting tasks with explicit comments that illustrate their logic and approach. This exchange of knowledge and practice have proven to be very effective and fruitful. So, join and show us how you do your code, share your ideas and don’t forget to comment, here we value your input.