Comments sometimes seem to be a hot button for software developers. Opinions range from the manager I had who actually did want a comment on every line of code to the people who think comments are completely unnecessary. I tend to fall somewhere in the middle as I think most people are. We may draw the line differently but most people think there is a sweet spot for how many comments are a good idea.
Some people don’t see the value in comments. They believe that code should be self documenting. The variables and functions should have descriptive names for example. To some extent that is a valid goal. Code should be understandable by itself. That’s not always as easy as it seems. When we write code we do so with some specific, obvious to us at the time, information. This might not be the case for others who come to the code later. Or even to the original programmer after some time has passed.
When I talk to students about comments I often relate an experience of my own. I wrote a really cool (in my opinion) program while I was a university student. It drew pictures on a drum plotter. Pictures took about a half hour to draw on that device. Some years ago, decades after I wrote the original program, I decided to write the program again for a modern display device. I wrote the program, compiled it, and ran it. It didn’t look right at all. I stared at the screen and thought “that looks familiar. I think I made that mistake the first time.” Now it turns out that I still had the punch card deck (yeah, I’m that old) and could read through the original program. I came across a comment that read “this function takes degrees in radian” Ah, ha! That is what I got wrong both times. I simple fix and my program worked as I wanted.
Clearly writing comments, especially that one, paid off big time.
Something that took a while to figure out should always be commented in my opinion.
When ever the subject of comments come up someone brings up the case where code changes mean that comments do not match the code. There is no doubt that this happens but frankly I have no sympathy for the situation. A serious professional should be mindful of details like that in their code. When the code and comments do not match it means someone was in too much of a hurry to do a complete job.
Comments should document difficult things, non-obvious things (parameter lists to called methods are a good example, and anything that required some involved logic.
Student projects in a first programming course often don’t have the sort of complexity that a larger professional program might have so it is hard to get students to comment code. I always insisted on a complete header of comments at least. And a comment that describes the purpose of each method written. As I think on it today, I wish I had produced some larger piece of well commented code to have students read.
How do you feel about comments in code? And how do you communicate it to students? Please share some ideas in the comments.
3 comments:
I fall into the category of one who ‘writes a lot of comments’. The older I get the more I realize that I use comments as an after the fact reflection on what I just learned. There’s something nice about going to some recently finished code and summarizing it all in comments. It really solidifies a lesson about what I just did. I do encourage my students to use them for the same reason.
Comment the heck out of. They are easy to remove later.
What requires commentary is not just subjective, it depends on the context of the writer. Students in a CS1 course may still find code unfamiliar, and so feel there is value in explaining something that would be a common idiom to more seasoned coders. In the extreme you may get code like:
print("Hello World") # Prints "Hello World"
I think it's easy for educators to forget that what seems useless to them may seem helpful to the writer. Perhaps students should be guided to think about what's appropriate to a particular audience.
Post a Comment