DEV Community

Discussion on: The Importance of Quality Comments

Collapse
 
florianschaetz profile image
(((Florian Schätz)))

Personally, I consider the Bugfender example a code smell, perhaps even an anti-pattern. Write the code clearly. If you need, add a function with a clear name. Then you do not need to repeat what the code does in a comment, because, reality shows us, that the code will change, while the comments will not. So, at best, the comments are redundant, at worst, they will be incorrect.

It's a good idea to comment on the WHY. "Why do we take the first three characters from this stream here?" "Why does this method add +1 here?" etc. These comments are great, they are important. But not comments about the WHAT. The code itself should make absolutely clear what it is doing, making any comment about that useless. Comment the intent.

Also, sorry, but comparing a few lines of a simple method to a indenting orgy isn't fair and the indenting orgy would not be better with more comments - it would be worse. The way to make that code actually clear is to refactor it, adding a lot of methods - but NOT to add more comments into already horrible code.