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.