The 8 most meaningless code comments

Over the years, I've had the great pleasure of working with some of the most humble companies and clients. This has given me the opportunity to work with a variety of different programmers - each with their own unique style. In fact, each project has some unique elements in itself.

The intersection of these qualities got me thinking about the code I've reviewed, updated, or improved. It's not so much the actual logic of the code, but the comments that the developers themselves added to the code that have had a profound impact on the code. The subject of this article is to list some of the code comments that have impressed me.

Because Carol asked me to.

I remember when I was reviewing the code, there was a comment that said:

 // Because Carol Told Me to Do This  

When I read this line of code, I was confused, "Who is Carol?" and "What did Carol ask this developer to do?" Although the programmer who wrote the code knows these two answers, for an outsider or someone who was added later, this comment is worthless. When I told my manager about this comment, he laughed and just said that Carol is obviously a person's name, and nothing more. Well, until now, I still don't know what this comment means.

A large part is obscured by code

In another case, I believed I had narrowed down the problem to a specific class. But opening the class, I saw a ton of code that was block commented out. What was crazy was that the commented code was in the middle of a method. So, after reading the top of the code, I had to scroll down a few screens before I could read the rest of the code. You have to keep it in mind, but luckily it wasn't too long in between, and there was a link to the source code repository for the application.

In my mind, I was very scornful of "reading a large block of code with no comments ahead of time and just seeing what the program does". When I asked another developer why the code was commented and checked like this, he responded to me with "just in case we need it next time". I was really speechless.

Just to have fun in misery

While working on a web-based application, I came across the following JavaScript comment:

 // make sure it's correctly formatted, because in javascript things  
 // like '7' or '4.3' or 'derpdy do 77' are valid dates  
 // seriously, try it out for yourself: Date.parse('derpdy do 77')  

The developer here realized that there was a problem with the Date.parse() method. To warn others, the developer decided to add a comment as a warning, while having a little fun. I can only imagine how frustrated the developer was when he realized that this was a dead end.

Apologize

Sometimes, programmers realize that what they are doing is not a good idea. Many times, this is the only choice that can be made outside the development team. So, there are comments like this:

 // Sorry for what you are about to see  

Reading the code and understanding the circumstances behind the implementation helps to fully appreciate a simple apology comment. It's a bit like that scene in a thriller where the hero apologizes before taking a planned action.

Just code around it

What started out as a whiteboard statement eventually moved to the following note:

 // Doing this to "not do anything to effect Eric and Steve's code"  

Basically, it's an entry point to a process, and the code works around a problem that was apparently introduced by Eric and Steve. But I don't have any background on this, and I don't know Eric and Steve personally, I just know that any code that affects them has to be disabled.

Annotation for the sake of annotation

We have all heard the saying "good code is self-documenting". I completely agree with this statement, and of course some comments are necessary. However, the following comments clearly do not fall into the category of "necessary":

 return   true ; // returns true  

This comment is obviously unnecessary since it's easy to understand what is returned. The only reason I can think of for this comment is that the developer used comments to work out the method before adding it to the actual code and then forgot to remove the comments. But if there is a code review process, such comments will not appear.

Incorrect comments

Remember the phrase "good code is self-documenting" mentioned earlier? Well, perhaps the worst of all comments is the one that provides error information. Take a look at the following simple example:

 // Always returns false  
 public   boolean isActive() {
 return   true ;
 }

The examples I've seen in reality are far from this simple. However, what's worse is when you need to rely on comments to write a complex method, only to realize that such comments are invalid. In this case, no comments are better than wrong comments.

Novel-like notes

One type of comment I've seen is one written by a developer that reads like a novel:

 /**
 * This is the widget method which will process the list of
 * widgets from the widget controller and service in order to
 * handle pre-processing (where the widget information is
 * compared against the average widget history), actual
 * processing (where the quarterly, monthly and week attributes
 * are updated) and all of the post-processing (which include the
 * analytical metrics and audit table updates) aspects. It is
 * important to remember the widget rules around leap year where
 * the cost to transfer rate is 75% adjusted to the annual rate in
 * order to account for the extra day. When this happens, the
 * process will throw the LeapYearException which will need to be
 * validated by the application support staff. Failure to do so will
 * end up causing issues with the ME-4110 report.
 */  

My rule of thumb is that any code that requires that much information should probably be broken down into smaller methods. And such information in comments should be moved outside of the actual code. In the example above, the business rules and business processes are recorded like a running account - but they may change over time.

in conclusion

A simple search on the internet will reveal a lot of information on how to write good code comments correctly. Some of them may even tell you how to avoid providing comments in your code as much as possible.

Instead, I want to share some of the hilarious comments I've had the pleasure of reading as an application developer. Keep in mind, I have 20+ years of experience in application development - reflecting the exception, not the rule.

Happy coding!

Translation link: http://www.codeceo.com/article/8-useless-code-commenting.html
Code Commenting Patterns
Translated by: Coder.net – Xiaofeng