Comment on "An Appeal to CS Teachers"

I recently read An Appeal to CS Teachers on 8th Light which talks about recent graduate programmers using far too many comments. This resonated with some experiences I had, and links back to an earlier post here, Programming 102, on teaching Java and Unit Testing. In this article Dariusz Pasciak comments on the problem of students commenting every line of code, and proposes two reasons that this might be happening:

It helps teachers read the code. 

It forces students to think more about what they're doing.

Here's my response...

I've taught university CS programming (most recently Java to 1st years, but programming in the context of other topics and a few other languages over the years) and usually give (just a few) marks for "appropriate" comments.

Particularly for the early years of a degree I do find I have to guide many of my students towards "useful" comments, rather than per-line or somewhat random commenting. A few are doing this because they are working out what is happening and worry about coming back to something that makes no sense. A few have been told somewhere in the past to comment everything, as suggest in Dariusz's post. Some are just erring on the side of caution, reasoning that "if Dan likes comments more can't hurt, right"?

The two rationales are interesting. 

It helps teachers read the code.

First, I should say that most students write coursework solutions that really aren't hard to understand, although in more openly specified projects why they have chosen to write the code like that maybe less so. However, the ones that are hard to understand are often those that have missed the point somewhere along the way and are most in need of some understanding and helpful feedback. For helping me understand what the students have written I've moved to unit testing.  Even the baroque enthusiasts and somewhat confused can write fairly understandable tests.
It forces students to think more about what they're doing.
As Dariusz says "Students just beginning to pick up programming already have a lot to think about.". Quite. There isn't any need to make life harder, it only ends up obscuring the point. The unit testing also works for thinking about what they're doing, but separating the thinking step out. More thinking when you're writing code that's at the edge of your ability isn't going to end well for anyone. Have a think then do the doing. Write a test; make it pass; refactor.

My standard advice to students is something like:

•  Write me a test case, that describes the intention of the method pretty well (unless we're talking about trivial getters, setters etc).
•  A good class / method / variable name removes the need for a sentence of comment. That may not remove the need for comments, but eliminates stuff that just clutters the code up.
•  JavaDoc style per-class and per-method comments are useful for an overall picture and also for describing how to use the code, which the code itself might not make so obvious.
• By all means comment some non-obvious step, clever trick or thing to come back to. Probably at a block within a method level. Then think about whether that bit would be better refactored into something else. At that point the comment may well vanish.

So, I'm with him: no need to hide the code in a flood of comments!