Tuesday 19 August 2014

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!

Friday 1 August 2014

Softly Softly

It has been nearly a month, so what progress?

Firstly, I've had a lot of admin to deal with. Most necessary, little passes the "interesting things with interesting people" test, none merits writing further about right now!

I've been working on a website in my spare time, using Ninja (discussed elsewhere). There's been quite a lot of learning along the way (a bit more about actually using Ninja, finding my way round Bootstrap, learning how Injectors work, revisiting graphics programming I last did many years ago, weighing up design approaches...), and at some point I hope to distill a post of things that are useful, repeatable and not covered thoroughly elsewhere out of this. Right now that isn't ready. The next step involves me broadening my NoSQL horizons a bit. I can see the steps from here to a first public version, just need to find the play-time to take them.

Another project has involved a lot of looking at licences and other legal stuff, and considering how that fits products that are still being developed and a lot of "what ifs" about future investors. It isn't the technical side of building a thing, nor the working for people. It matters, a lot, to the business though so it merits the investment in time. We've also had some really excellent partners giving us advice, so thank-you to them. However, there's very little I ought to openly say about the detail. We've been "nearly there" many times over quite a long time, but today some of the deals were signed. Which is a relief.

So, the blog isn't dead, I haven't had an extended holiday and done nothing, nor taken up basket weaving. But it has been a "bunch of stuff" sort of month, rather than a "here's a thing" sort.