I was watching a presentation recently on refactoring C# code and was amazed by some of the comments that the speakers showed in the code. The example was a real application that had been obfuscated and simplified a bit for the talk. The comments, however, had only been changed when they might disclose a specific person or company. The speakers pointed out a few of those changes, but also noted that most of the comments were verbatim from the original code.
Comments like “Dave changed this from the old way” or “Bug 445: as per the operations group” were good examples of bad comments. These items don’t really help a developer understand the code. The comments in application code should be there to add to the code itself, helping someone understand a reason for the code, not an obscure reference or an obvious statement (“this code adds two balances together).
With that in mind, I’m sure many of you have come across some comments in code that have evoked a wide range of emotions. I’m sure you’ve been frustrated, annoyed, or something else. Perhaps even from your own comments. With that in mind…
What are the worst comments you have found in code?
I hope you don’t have examples in your current application, but perhaps you do. Perhaps you have even committed your own code recently without really taking the time to accurately describe the change. Maybe you want to go look in your VCS and see what you’ve entered lately.
Steve Jones
The Voice of the DBA Podcast
Listen to the MP3 Audio ( 2.0MB) podcast or subscribe to the feed at iTunes and LibSyn.
Voice of the DBA 
In some of my scripts, I use loops. While it’s easy to pick up that it’s a loop, I always add comments to describe what the loop should be doing in its entirety. This makes it very clear about the intentions of the entire loop, so others don’t have to go line-by-line to figure out why I’m looping in the first place.
LikeLike
The worse comments in code, NO Comments at all. I deal with a lot of third-party developed code either produced by the vendor or developed by consultants. Because they are in such a rush to deliver the ignore any documentation. Now if I’m in the loop I make sure there is basic level of documentation.
LikeLike
Upon getting a request in to review a poor performing stored procedure the comment was found “This is probably not the best way to do this”.
LikeLike