Why we comment code (Yet Another Code Commenting Article “.yacca”)

First question: Do we really need another article on code commenting?

I think so, it is a topic like Exception Handling that benefits from more opinions being expressed.

I have recently participated in several discussions regarding code commenting in Java and Agile projects and based on those discussions I want to document and share some thoughts on commenting code in general and for Agile teams.

On the most basic level, why do we comment code? 

One of the most important aspects of code is that is usually not static; code is updated, enhanced, repurposed, modernized and serviced because of bugs and many other activities touch code. Code we write will be read and modified by people, including your future self. Even you will need to work with the code during the Sprint the code may be debugged and modified in the future. 

Regardless of who will work on the code or when, useful commenting makes that work faster and reduces the opportunity for defects.

While what the code does should be "self-evident" from reading of the code, the syntax does not communicate what you intended to do; it is possible (however unlikely) you implemented the requirement incorrectly or made a logic error.  

Consider also that there are many ways to implement the business logic on how to fulfill a requirement. I’m sure the developer always has correct, insightful and well-reasoned thought processes behind why a bit of logic was implemented a certain way; but you need to document in comments why you used that specific implementation. 

Comments will answer questions about implementation choices and design decisions without future maintainers guessing (and second-guessing) the developers’ reasons and allow them to determine if the implementation is still the best implementation as the application evolves and business requirements are refined or changed over time.

Of course not all code needs the same level of commenting; DTOs do not require much commenting but more complex implementations can and should have more comments than code. Common sense must prevail; there is no benefit to commenting much beyond the JavaDocs on getters and setters unless you’re doing more than just assigning values to and returning values from properties.

There are many other things that do not need commenting, such as who makes changes or the date changes are made; that is in source control. The code self-documents what is being done, comments tell how and why it's being done - don't duplicate your effort.

There are some common objections to coding heard frequently:

“Commenting is not necessary if your code is written well”: Commenting is necessary because you need to tell people what you intended to do and why you chose to do it a specific way. This is especially important in Agile groups and other organizations where uncertainties are often discussed with the Stakeholders or other team members directly. People that were not part of the conversation need to know the decisions made in those conversations.

“Comments slow you down”: Any reduction in pure speed of laying down lines of code is negligible; I’ve timed it. I spend at most 10 to 20 minutes commenting a class that took 3 to 6 hours to write. Also, just like in architecting a system, the implementation that completes a process in the shortest elapsed time for a single user may perform very badly under load. 

 I also find that while I am writing, comments help me to complete my work for a User Story faster because of readability and comprehension is increased with commenting.

 “Comments increase LOCs and increase maintenance costs”: Comments are NOT counted as LOCs and absolutely do NOT add to maintainability costs; they do just the opposite because they help developers understand the code now and in the future. Does anyone seriously suggest that Continuous Integration is wasteful because it slows you down when coding? Commenting is just as important as CI.

“Commenting is documentation and not an Agile practice”: Two problems with this; for any application with multiple releases and production support, documentation is vital and “Being Agile” is not an excuse to not document. The right level of documentation in Agile is the right info for all the stakeholders to do their work but not more than is needed for that purpose.

The Agile Manifesto does not say “don’t do documentation” it promotes “Working software over comprehensive documentation” and “That is, while there is value in the items on the right, we value the items on the left more.” The term “comprehensive” documentation in this context really means “more documentation than is needed and before it should be written”

Example:

I have an example of a class that illustrates the point I’m trying to make. I was taking a Statistics class for my MBA and the class was discussing the “Monty Hall Problem” (https://en.wikipedia.org/wiki/Monty_Hall_problem). I wrote a quick Test Harness that would allow me to run a simulation of the problem and vary the number of trials and even the number of doors.

I’ve included on GitHub the Test Harness class both with and without commenting. To be honest, I did over comment the code in this example. That being said, I still didn’t spend more than 30 minutes commenting the code. Between Code Reviews and future maintenance, more than 30 minutes of time will be saved. 

The example Monty Hall Problem code is available in GitHub: https://github.com/mgeiser/MontyHallProblem

Evaluate the MontyHallProblem_NoComments.java version of the class first and then evaluate the MontyHallProblem.java code. 

Assume you have a Defect reported that the output is faulty. Which version of the code will be easiest to debug and find the error or, as is likely with the case here, that the code works as designed and the reported Defect is “Works as Designed – No Defect”?

I have tested the effect of commenting on productivity in real life. I had a new component that extended the Password Policy of an Identity and Access Management system my employer at the time was using to enhance the Password History retention. Two configuration options were “The number of interim passwords before a password could be reused” and “The minimum number of elapsed days before a password could be reused”. 

Assume the “Number Password History Retained” value is 5 and “Minimum Days Between Reuse” is 90 days. The intent was with those settings for the two rules that a password could not be reused for both at least 90 days AND until 5 other passwords have been used in the interim. The initial code had a defect I that the code did a logical OR not and AND in the implemented code; if you changed your password 6 times in a row, you could reuse the same password that just expired. 

I gave the same code, one with comments and one without comments, to two very good and equally skilled mid-level developers. The developer with the comment code completed his work more than an hour sooner than the developer with uncommented code. 

My guidelines for commenting:

• Comment what you intended to implement (the code self-documents what you did implement).
• Include explanations of how tricky and clever bits of code work (for people not as smart as you).
• Reference the User Stories/documents for the requirements you’re implementing
• Capture implementation and other design or scope decisions (for example: why you chose a specific implementation such as a HashMap over a TreeMap or a LinkedHashMap).
• Err on the side of too much commenting, especially when writing new code. As you review your code before check-in, commenting that needs to be tightened up will be obvious.
• Commenting has a great ROI. Make clear expectations on commenting part of your standards and your Definition of Done.