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.