The Beginning…

When I first started my Computer Science degree program, I remember the various discussions on how and when to comment code.  Each text book that I read had different views on when and why someone should comment their code.  On top of the different textbook teachings, each of my professors seemed to have different standards on comment requirements: ranging from some not mentioning comments to some deducting points if comments were not present.  One common trend was that the quality of code comments did not matter.  My internal thoughts were that commenting in school was simply a lot of noise.  We were shown practices where we would comment everything and not necessarily in a good way.  I would see things such as:

[code language=”java”] // declare counter
int counter;
// initialize counter
int counter = 0;

// loop printing numbers
while (counter < 10){
System.out.println(“Number: ” + counter + “.”);
counter++;
}//end while loop

[/code]

While this code is communicative, it’s also busy and the extra markup is distracting (in my humble opinion). More so, any programmer would know exactly what this code is doing without the comments.  Of course, this is pretty basic stuff, what struck me was that the comments that we were required to write in school, went against my natural inclination to communicate decisively and not just because I could.  Wait what?  Let me clarify a little.  I believe that communication is important in many situations, but sometimes communication can be more confusing when it’s not clear, concise and free of extra irrelevant information.  It’s like someone trying to tell you that they are ready for dinner by singing the National Anthem while inserting the words “I’m ready for dinner” somewhere within the song — it’s just extra unneeded noise.  I personally feel as though unneeded comments can play the same role within our code.

So, what now?

I vividly remember my Google searches on a standard for commenting code and what I found was troubling for a new developer at the time.  Within one forum or within a single resource there were many different opinions broadcasting why their means of commenting was the best.  There were folks lobbying that code should be self documenting and that comments were unnecessary in many cases.  There were others that felt that more communication didn’t hurt and whatever meta data could be added to the code base would only benefit the project, not harm it — specifically for new members to development teams.  The two sides warred with many people also falling in between at different areas of the spectrum.  The one thing that was clear was that there was in no way a specification when it came to commenting code.

With experience, came clarity…

It wasn’t until I started working on a development team, that I started to find my own practices for code comments.  First and foremost, I tend to lean towards code that is self documenting.  I use explicit comments when there is business logic specific to that code that may not be abundantly clear to the person that is maintaining the code.  I am also primarily a Java developer so I believe in commenting in order to get all of the benefits from the Javadoc functionality.  I’ve found that usually if there is a need to comment sections for flow, there is a better design that can be accomplished without using comments such as breaking the code out into different classes or using private or helper methods and descriptive variable and method names to add concrete metadata to the code.  This methodology is not new and can be found in well-known software books such as Clean Code by Robert C. Martin.

I’ve found that taking more time to think about the design of the code, leads to fewer comments being needed.  Many may think that comments aren’t hindering the program in any way since the compiler ignores comments.  This is true, but comments can be easily ignored by the programmer, as well.  I’ve seen situations where code was changed to fit a new business need, but the comments for that code was not updated.  This leaves very deceptive code that can be more confusing than helpful.  In some situations, the original comment was necessary and the developer updating the code should have been more careful.  But I’ve also seen in some cases where the newly-deceptive comment was simply meta data that could have been placed in an external documentation source such as a wiki.  In this situation the wiki was updated, but the source code documentation was not.

All-in-all, I believe that it’s important to find the standard on the project that we are working on.  Having a specification is a helpful means of determining how code should be commented, for a project may have a specific standard that should be followed.  However, in many cases, it’s up to the developer to find a happy medium in the spectrum of commenting paradigms that exist today.  I suppose that one test we can use for ourselves is to return to code that we wrote say, 6 months ago and see if we could follow it.  Is there enough information to understand the flow and purpose of the code?  Would refactoring the code make it far more clear to a new comer?  There’s always room for improvement, moreover, returning to our old code is a great way test our own system of commenting.

I’ll leave you with this: what I can say is that my current standard for commenting is completely different than what I was taught in school.  However, it feels really good to have a personal standard, developed through my own research and experience.

Mira is a Senior Full Stack, specializing in Web Applications developed in the healthcare industry.