Refactoring Comments into Better Code
function(commentedCode) { return betterCode; }
In my last article I touched on the importance of commenting code carefully. Comments aren’t at all evil, but more often than not they can be rewritten into cleaner code.
Check out gitconnected >
The community for developers and software engineers
I still believe that sparse commenting is good commenting. Too many comments is useless noise. I just recently came across this piece of code which serves as a good example of the potential noise comments can make.
On line 13 it is declared that the next looong line code will “Check if we’re overwriting an existing function” with a comment. This violates the long held principle of DRY, since the author has to repeat what they are doing in both code and comment. If one is ever updated without the other, by anyone, that comment is probably wrong. Since the mental overhead of line 14 is such a pain, it is kind of the author to try and help future readability. But if we simply return line 14 from the function methodAlreadyExists(name, prop) 13 and 14 in the context of this function become
if (methodAlreadyExists(name, prop)) { }
The confusion is stripped away, the self repeating is squashed, and our code already reads more like prose. Delightful!
So with some reflection and insightful feedback, I would like to commend the spirit of commenting code. Whenever you are inclined to comment a piece of code, first, I thank you! You should pat yourself on the back! You are being considerate to future you and all other readers and tinkerers of your code. But then ask yourself if there is a way to solve this problem with code alone. Sometimes the answer will be no, at which point, please write a comment! Succinctly and accurately, save everyone from the burden of re-understanding esoteric and hard to read code. Commenting code is easier than refactoring to achieve the cleanest code possible. Refactoring can be hard work, and iterating takes time. We all strive for the same goal: to communicate in plain English those things which are difficult or time consuming to read in code. Comments are prone to decay and misdirection, and can often violate the DRY principle. The code is the medium. The better we can express our ideas in the code itself, the less we will need comments to explain things for us.
Comments are not evil. Comments are simply one of the tools a developer has at his disposal that can be used for good or evil. My intentions were to warn against needless, and more importantly excessive use of comments, by pointing out the main drawback of overuse that I’ve found through my experience — namely that outdated comments can be misleading and are often overlooked during development and maintenance — and suggesting simple ways to combat it, I could hopefully save my fellow coder and their team a few headaches which I have needlessly suffered.
