Programming Proverbs 18: Use Comments

Computer Science Teacher
Computer Science Teacher - Thoughts and Information from Alfred Thompson

Programming Proverbs 18: Use Comments

  • Comments 5

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.

  • Yes, comments can add value, but to quote from "The Practice of Programming" (http://cm.bell-labs.com/cm/cs/tpop/index.html), which I believe is a must read for all programmers

    "Don't belabor the obvious..."

    "Comment functions and global data..."

    "Don't comment bad code, rewrite it..."

    "Don't contradict the code..."

    "Clarify, don't confuse..."

  • I agree with all of those suggestions. Comments are one of those things where "just right" is what one is looking for. Too much is as bad as too little. One thing that I have found, and those comments suggest, is that the act of writing comments sometimes makes things more clear in a way that points out they should be done differently.

  • Most intro programming courses I've seen emphasize comments to an insane level.  The commenters above make a good point -- there is a balance to be struck between enough and too many comments.

    Working in industry, I find myself adopting another extreme: preferring no comments at all, other than at the top of a function (purpose, parameter descriptions, limitations, etc).  As software changes (it is inevitable it will during development and during the 80 percent of its lifetime in maintenance), comments are rarely updated.

    As I've seen it, people barely update the comments that they write, and they almost never update the comments in the code that other developers write.  I can't mention how many times comments have led me or my fellow programmers astray.  Sometimes, the original comment is often wrong -- sad to say, but sometimes developers aren't the best at writing.

    A professor once told me, "never trust comments -- comments lie, code doesn't lie."  It sounded pretty cynical at the time because I used to be a stickler for comments, but after spending most of my career modifying and upgrading code, I've come around to agree with him.  It makes sense though, comments are just an interpretation or informal notes of the formal code that is right there.

    As for beginning students though, I think there's a lot to be learned about writing things down, be it in comments or something else.  It's part of being a good programmer or a software engineer: drawing a picture or diagram of the problem, expressing the design or approach in writing.  It helps one think of the problem in a clearer sense and it helps enforce good practices: being able to clearly communicate the design to other teammates and to make notes so one remembers what they did.

  • To offer a counter point ...

    Years ago, in industry (prior to jumping to teaching computer science), I worked with a wide variety of engineers and programmers. The engineers, to their credit, tended to comment well: not too much, not too little. The programmers, however, tended to commente little if at all. (Yes, this is an indication of the difference between the two mindsets and levels of training.)

    The worst case of the latter came from someone who most of my students know as "Bob" (not his real name), who tended to never comment if he could avoid it. He was the sole programmer of a large project over many years, and had written hundreds of thousands of lines of code in assembler. When asked how he can remember what individual rountines did, especially when he had to support it (i.e., fix bugs), his response was "well, since I wrote it, I can usually figure out what it does, and if I can't figure it out within about 15 minutes, I just rewrite it."

    Unfortunately for the company, his attitude gave him a kind of job security: the company couldn't afford to lose him, since no one else would likely be able to figure out how his stuff worked. The dark side of this is that he will never be able to move onto other projects (until the product is discontinued), because he is too valuable to that one product. But from the company's standpoint, if anything happens to him, they're sunk!

    These days, I tell all my programming students about "Bob", because they need to know that commenting code is an essential skill. Those who adopt simple standards will be more "marketable" in the future than those who don't.

  • I found this Programmer Personality test the other day. It is based of the Myers-Briggs Personality Test

Page 1 of 1 (5 items)