Code Commenting Patterns

Over the years, I have had the fortune to work with a modest list of companies and clientele. With each opportunity, I came into contact with a wide range of programmers - each with their own unique style. In fact, every project itself has had some element of uniqueness when compared to the others.

I've found that the intersection of these qualities has trickled down into the program code that I once I had review, update or enhance. Not so much in the actual logic of the code, but the comments added to the code by the developers themselves. The topic of this article is to list some of the comments that I will probably remember for the rest of my career.

Because Carol Said So

I recall reviewing program code where the comments were as noted below:

// Because Carol Told Me to Do This

Reading this line of code, quickly made me wonder, "who is Carol?" and also "what is the 'this' that she wanted the developer to do?" While the programmer was in a position where both answers were known, to an outsider or someone down the road, this comment would really add no value. When I told my manager about the comment, he laughed and simply said "Carol" obviously sparking memories just from mention of her name. Still, I knew that I didn't want to ever get on Carol's bad side ... if I ever came to know her.

Huge Section Of Blocked Out Code

On another instance, I believe I narrowed the problem down to a particular class. Upon opening the class, I saw a huge section of code that was block commented out. The crazy part was, the commented code was in the middle of the method. So, I was able to read the top part of the code, then would have to scroll down a few screens in order to pick up where the actual code left off. Keep in mind, this wasn't too long ago, so there was a source repository linked to the application.

In my mind, I sarcastically thought, "let me go ahead an uncomment out this HUGE block of code, just to see what the program USED to do." When I asked another developer why the code was commented out and checked in as such, the answer I received was "in case we need it again." I had no response.

Just to Add Comic Relief Over a Frustration

While working on a web-based application, the following JavaScript comment was discovered:

// 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')

Here, the developer realized there are issues with the Date.parse() method. As a warning to others, the developer decided to add comments as a warning, keeping things light-hearted while doing so. I can only imagine the frustration that was felt when the developer realized this unexpected result.

The Apology

There are times when programmers realize the approach is bad. Often times, it is the only option, based upon decisions made outside the development team. In one such instance, I recall seeing the simple comment:

// Sorry for what you are about to see

Reading the code and understanding the situation behind the approach implemented put me in complete understanding of the simple apologetic comment. Kind of like a scene in a block-buster thriller where the hero apologizes before taking a planned action.

Just Code Around It

What started as a whiteboard statement, was ultimately transferred into the following comment:

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

Basically, this was the entry point into a process to code around an issue obviously introduced by Eric and Steve. I never received the background on this scenario or met Eric or Steve, I just knew that anything that impacted their code was considered forbidden.

Captain Obvious Adds a Comment

I am sure we have all heard the saying that "good code documents itself." I totally agree with this statement, but do feel that some comments are necessary. The line below, however, does not fall into this category:

return true; // returns true

Here, the comment really isn't necessary, since it is easy to understand what is being returned. The only reason I can come up with on how this comment was introduced, was that the developer used comments to map out the method before adding any actual code, then failed to remove the comments. However, that seems like a stretch to me ... especially if there was a code review process in place.

The Comments Are Not Correct

Remember when I mentioned, "good code documents itself" earlier? Probably the worst comments of all are the comments which provide incorrect information. Take the following very simple example:

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

The examples I have seen are far from this simple in reality. What makes things worse is when you rely on a comment for a complex method, only to realize the comments are no longer valid. In this scenario no comments are better than comments that are wrong.

The Novel

The last comment that I've seen is when the developer decided to write comments which appear to be novel-like in form:

/**
* 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 section of code that requires that much information should probably be broken down into smaller methods. If nothing else, the information in the comments should reside outside the actual code. In the totally made up example above, business rules and business processes are being documented - which are likely to change over time.

Conclusion

While I thought about including guideless for proper code comments, I am certain that there are endless such references online which can be found with a simple search.  Some even going as far as to state to never provide comments in your code.

Instead, I wanted to share some of the comical comments I've had the pleasure to read in my years as an application developer. Keep in mind, my compilation spans well over 20 years of application development - certainly reflecting the exception and not the rule.

Have a really great day!