The Curse of Excessive Commenting

Good comments can improve the readability of code. However, over-commenting can do the opposite. Unnecessary comments waste both space and the reader's attention without adding value. Many lines of code do not require additional explanation. If you find yourself writing "// set i to 0" before the line "i = 0;", you are doing something wrong.

The town's blacksmith, Drex, had been cursed. Drex freely admitted that he had provoked the wizard, but the curse seemed like an extreme reaction. The wizard could have simply insulted him back or walked away. There were plenty of reasonable options. He did not have to curse Drex.

As annoying as the curse was to Drex, his apprentice Rachel was suffering more. The Curse of Excessive Commenting was designed to annoy both the teacher and the student. Whenever Drex explained something, he now did it in excruciating detail.

"Now, watch how I form this hinge." Drex instructed his apprentice. "First, I pick up the metal with these large tongs. They are made of a heavier metal, so they will not burn or melt in the fire. Then I use the tongs to put metal in the fire where it will heat up."

As he spoke, Drex grabbed a small blob of metal with his tongs and shoved it into the fire. After a moment, Drex felt obligated to add "I am still heating it up in the fire." He reiterated this observation five more times before the metal was hot enough to work.

"Now I will use the hammer to flatten the metal." Drex explained. "I am hitting the metal with the hammer. I am hitting it again. I am hitting it again."

Rachel stood off to the side, watching. After the tenth repetition of "I am hitting it again", she rolled her eyes. Not only were these descriptions incredibly annoying, but it also made it hard for her to actually follow what was going on. Drex was narrating at such a low level that it was difficult to pay attention to the high-level flow. The concept of forming the hinge was overrun by a constant stream of tiny details.

"I am hitting it again." narrated Drex.

The first time that Drex had described the process of making a hinge it had been simple. He described the entire first ten minutes of work as: "First, flatten out a small piece of metal." That is all. He had left unspoken the low-level details that any blacksmith should easily pick up -- to flatten metal you heat it and hit it with a hammer.

"I am hitting it again." narrated Drex.

The commentary was driving Rachel crazy. She thought back bitterly to the encounter with the wizard three days ago. Drex had confronted the wizard to complain about his magic candle. The candle had burnt out, which is exactly what magic candles should not do. When Drex had discovered that the candle was the creation of the wizard's apprentice, he had made the fateful mistake of insulting the wizard's teaching skills. "At least I tell my apprentices what they need to know." Drex had bragged. It turned out to be a mistake to taunt a sleep-deprived wizard at two in the morning.

"I am hitting it again." narrated Drex.

At least the wizard was not evil. He had placed only a temporary curse on Drex, forcing him to over-comment on all of his actions for the next week.

"I am hitting it again." narrated Drex.

Unfortunately, Rachel did not know if she could last another four days.

-----------------------------

Also read about the importance of good comments in baking. Or read more about Drex in Loops and Making Horseshoes.

The Importance of Good Comments: A Tale of the Baker's Apprentice

Comments are additional text within code that provide explanation. Comments can greatly improve the readability of code by providing insight or summarization. For example, a clear comment before a large block of numeric statements might simply explain "Solve a*x^2 + b*x + c = 0 for x", allowing the user to understand exactly what the following block of code is meant to do.

As part of his world renowned teaching program, the famous baker Breadtista insisted that each apprentice thoroughly document his or her work. Thus, apprentices created a reference that would live beyond their apprenticeship. All recipes, tips, and tricks would be clearly documented. Breadista strongly believed that such a resource provided his apprentices with a significant advantage.

As Breadtista was fond of pointing out, the key to a great recipe was capturing the perfect amount of information. Where other bakers wrote recipe books filled with lists of bland instructions, such as: "Add two eggs and blend well", Breadtista insisted on commenting his recipes. These comments added context and explanation.
Here is an excerpt from Breadtista's famous eight-chili strawberry muffins:

Step 5: Cut the strawberries into cubes of 1cm per side. [This size allows the flavors to blend while preserving the fruit's texture.]

Step 6: Add the strawberries to the dough.

Step 7: Gently stir until the strawberries are mixed into the dough.

Since comments were not part of the instructions themselves, Breadtista clearly denoted his comments with braces [] to avoid confusing other bakers.

Further, Breadtista insisted that all comments provide meaningful information to the recipe itself. He hated recipe books by famous castle chefs that contained thirty page digressions of the author's lifelong quest for the perfect pancake. It was especially egregious if the recipe then produced chewy pancakes. Pancakes were not meant to be chewy, and comments were not meant to be life stories.

Despite his firm belief in the importance of good comments, Breadtista found it difficult to explain this philosophy to each new apprentice. Every year, he heard the same arguments:

• "Why should I comment? The only people reading this are bakers, and they should already know this."
• "I won't forget why I did that."
• "Isn't that step obvious?"

And every year, he repeated the same answers:

• “Just because it is obvious to you, does not mean that it will be obvious to others."
• "Just because it is obvious to you now, as you are writing the recipe, does not mean that you will remember it."
• "If it is so obvious, why did I have to draw you an example on the chalk board? Twice?"

Each year, after lecturing on the importance of clear comments, Breadtista would have at least one apprentice who took the idea too far. For example, one year he had an apprentice who wrote the following instructions for making simple bread:

Step 1: Measure out 1/4 of an ounce of yeast into a small bowl. [We put it into a bowl so that we can add water in step 2 to activate the yeast.]

Step 2: Add two table spoons of warm water to the bowl with the yeast. [We add the water to the bowl in order to activate the yeast.]

Step 3: Wait 5 minutes. [We wait 5 minutes in order to allow the yeast to activate in the water].

Breadtista never made it past step 85 in that recipe. He "accidentally" spilled a full pitcher of water over the apprentice's parchment so as to spare anyone else from reading it.

It took ten years of trial and error, but eventually Breadtista found the perfect way to reinforce the importance of GOOD comments. The first three weeks of each apprenticeship, Breadtista would make each new apprentice work from the worst notes of previous students. Although it meant that he would now hear cries of "WHO WROTE THIS?" and "BUT WHAT DOES IT MEAN?" from the kitchen, this process saved him from having to repeat the same reasoning over and over.

Nothing reinforces the concept of understandable, well documented recipes more than having to read other people recipes.

---------------------------

If you are interested in learning more about writing good code, check out: The Importance of (Variable) Names or The Importance of Unit Testing Magic Spells.