Code Commenting Patterns - DZone Agile

Code Commenting Patterns - DZone Agile

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.

Read full article from Code Commenting Patterns - DZone Agile