To: Teachers of all programming languages
Over the past year, I have seen the code of many students who are working toward a degree that requires them to take a programming language class of some sort. One thing all these code bases had in common was comments—useless comments.
I believe that it is good to know what a comment looks like. I also believe that it is good to know how to write a comment (just in case). I do not, however, believe that it is good to write a comment for every single line of code. Furthermore, I am strongly against the practice of requiring students to comment their code extensively and penalizing them for not commenting their code.
Warning: the following is based on a real-life experience of a student in a CS course. His grade was adversely affected by some of the code you are about to see.
int appleCount; // an int that stores the count of apples
"We get a point taken off for every variable that isn't commented."
That is the response I received from one student after I asked why he had to write a comment to explain that int appleCount is an int that stores the count of apples.
Playing the devil's advocate and trying to come up with some really good reasons why students may be required to comment every single variable that they write, I could only think of two, each of them being easily dismissible.
- It helps teachers read the code.
- It forces students to think more about what they're doing.
It helps the teacher
Yes, some students write nasty code. Yes, some students write code that is nearly impossible to read. No, a variable declaring an int named appleCount is not nasty code, nor is it impossible to read. On the contrary, it is quite self-explanatory and needs no further clarification. The additional comment provides absolutely no value to the teacher reading the code.
It forces students to think more
Students just beginning to pick up programming already have a lot to think about.
For beginners, writing even the most trivial program already comes with a truckload of things to consider. Adding on the requirement of commenting "every single variable" is anything but helpful.
For non-beginners who already understand programming basics, being forced to think about "what else should I comment" is also anything but helpful. Instead, their efforts can be directed toward things like, "Which variables have bad names?," or "Which part of this code is unclear?"
So what can teachers do instead?
I can imagine some folks arguing for comments being necessary in situations like so:
int i; // integer counter for apples
What is necessary in this situation is a better name:
int counterForApples;
The latter example is perfectly sufficient for communicating to a reader what the variable is for.
If a student were to submit a piece of code that looks like the former example, then sure, go ahead and take off a point or two. However, don't do it on the grounds that the student didn't comment their variable. If you do that, then the student will focus their efforts on "comment everything." Instead, take off points on the grounds that the variable name was unclear. This will make the student focus their efforts on "what else can I make more clear?"
Comments
are accepted here:
$ echo ZGFyaXVzekA4dGhsaWdodC5jb20K | openssl base64 -d
