top of page
Search

Why Comments Are Bad For Your Code


I've noticed that extensions to enhance code comments are getting more and more popular (see BetterComments for example) and with it there bigger chances of misusing it.


Even though there can be very legitimate reasons to use such an extension, especially for personal projects, you should usually be careful with using it in bigger projects. Why? Because it can lead to increased maintenance and lower quality code.


You should not put any effort in making your comments better, but your code. The comments are ignored by the compiler and usually bring no added value.


Instead of writing comments and investing more time in installing various extensions, customizing them to stand out, align with the team for consistency of use, you should use this time to refactor the code to make it more obvious to the point the comments are no longer required. This brings more value which lasts.


Also, code gets changed/refactored at some point and comments usually don't.

At this point you actually make your life harder as you now need to maintain the comment content and the type of comment which might change.


Which of course nobody covers 100% or even not at all, so you are left with weird code with outdated, colored comments.


Now in case you work for a library/framework which others use, you might want to add some documentation comments to make it easier for people to work with your library. In such case, you have a double responsibility: ensure your code in the library/framework works as expected and is easy to use on one hand, and on the other hand the documentation comments should also be updated with the code.

In such cases, you need clear and short descriptions not extensions to color various comments differently.


Comments in code is usually perceived as a code smell. In the Basic Programming course, we cover the most common code smells and how to fix/avoid them.

You can further read about code smells on your own.

Comments


bottom of page