Programming Proverbs 18: Use Comments

Is there anything so obvious to an experienced programmer that is so hard to get across to students than comments? Students know that they are so smart that they will remember everything about their programs. And of course they think they are smart enough to figure out any other program they come across. I used to try to get across the point of comments by telling this true story.

Years ago I wrote a cute little program to generate geometric shapes spinning larger and smaller. I wrote the program in FORTRAN on punch cards. It ran on a drum plotter. This meant that I had to explain not only punch cards but drum plotters. See how I snuck a little computer history into the story?

In any case I decided to write the program again but this time in Visual Basic and for display on the screen. Being a smart guy I would do it from memory. Everything went great until the first display came up and it was all wrong. But it was wrong in a vaguely familiar way. I remembered making the same mistake 20+ years earlier. What I didn't remember was how did I fix it.

The good news is that being a pack rat I had the original deck of cards in the attic and was able to find it. Sure enough I had a few comments in it and one of them said "this function takes degrees in radians." Yep, that was it - I was using the wrong unit of measure. A few minutes later and my program was doing what it was supposed to be doing. I have no idea how much time that one comment saved me but it was a lot.

This story usually makes an impression. Does it always get students to write enough comments? No, but there is improvement. And they remember the story.

I think the key learning there is that if something gives you trouble, if it is confusing or if it caused you problems with debugging or getting the algorithm right than you should comment it. Anything things that costs time once will cost time again if not explained properly. Do that and you will thank yourself later. Or someone else will thank you and that is a lot better than then cursing you out.

This is the eighteenth of a series of posts based on the book Programming Proverbs by Henry Ledgard. The index for the series is an earlier post and discussion of the list as a whole is taking place in the comments there. Comments on this "proverb" are of course very welcome here.