97 Things Every Programmer Should Know

Chapter 16. A Comment on Comments

Cal Evans

IN MY FIRST PROGRAMMING CLASS IN COLLEGE, my teacher handed out two BASIC coding sheets. On the board, the assignment read, “Write a program to input and average 10 bowling scores.” Then the teacher left the room. How hard could this be? I don’t remember my final solution, but I’m sure it had a FOR/NEXT loop in it and couldn’t have been more than 15 lines long in total. Coding sheets—for you kids reading this, yes, we used to write code out longhand before actually entering it into a computer—allowed for around 70 lines of code each. I was very confused as to why the teacher would have given us two sheets. Since my handwriting has always been atrocious, I used the second one to recopy my code very neatly, hoping to get a couple of extra points for style.

Much to my surprise, when I received the assignment back at the start of the next class, I received a barely passing grade. (It was to be an omen to me for the rest of my time in college.) Scrawled across the top of my neatly copied code was “No comments?”

It was not enough that the teacher and I both knew what the program was supposed to do. Part of the point of the assignment was to teach me that my code should explain itself to the next programmer coming behind me. It’s a lesson I’ve not forgotten.

Comments are not evil. They are as necessary to programming as basic ...