As programmers, developers, and engineers at one point or another we had come across that commenting your code is good. All good code contains comments and that is why you should use them, right? The answer is that it depends. Wrong usages of comments can do more harm than good.

My goal for this post is to share with you why comments can do more harm than good in some cases. To be clear, I am not advocating that you should completely stop using comments.

Manual Upkeep

Overtime as a project grows the code will change. As the code changes, it is likely your comments will become outdated. This means you will need to update your comments as your code change. Depending on the scale of the project, it can become difficult to keep the comments up-to-date.

The manual upkeep of comments is worst when it is not you who makes the changes to the code. The comments might not make sense to another developer, so they might leave those comments alone or remove them. This can cause confusion in the future.

Lost in Translation

Someone else might work with your code, which can change the implementation. This might leave lingering comments that are outdated and cause confusion. On the other hand, maybe they decided to update the comments but did not express the original intent well.

Sometimes code is worked on by multiple developers. Some change the implementation and leave the comments as is. Others change the implementation and update the comments. This can easily lead to a lost in translation with the comments. If the code itself is not expressive, it will be difficult for someone else to update the comments.

Commented Out Code is Bad

You probably have seen commented out code or blocks of code in a new project or in your old code. Even if it was your code, you might find yourself questioning why it is there but commented out.

One of the worst offenders is commented out code that has comments. The comments might say the line of code is a bug fix or allow feature X to work. I used to uncomment code like that thinking it really does what the comments say it will do. Of course, I find out uncommenting the line of code or block of code breaks the software. Nowadays, when I see commented out code, I delete it so it will not cause any problems for myself or other developers.

How to Use Comments Effectively

Using comments effectively is not the topic of this post, but I think it is important to touch briefly on this topic to point out that comments are not always bad. Comments can do harm, but it can also be used for good under the right circumstances. For example, comments excel in their purpose when you use them to explain briefly about a function and its header. The comment can briefly explain what the function does, what the parameters are, and the return value if any. Other developers can understand what a function will do without digging into the function’s implementation.

I hope you found this post helpful. If you found this post helpful, share it with others so they can benefit too.

What are your experiences with comments? Have you encountered any of the problems I mentioned in this post?

To stay in touch, follow me on Twitter, leave a comment, or send me an email at steven@brightdevelopers.com.