On Saturday, October 5, 2002, at 09:16 am, Russel Winder wrote:
I think comments within code are often a waste of time, at least
in high level languages. The code expresses the ideas logically
and unambiguously, which is much harder to do in a natural
language. If the functions and variables are given sensible
names, their meaning is usually clear enough. (Writing comments
or documentation outside of a program could be useful, however,
for example in giving instructions about how to use a class.)
Whilst it is clear that fatuous comments are a waste of space and time,
I think your position is overly extreme. Self-document code is a good
thing and as you point out most code can be self-document. This means
that there should rarely be a need for comments within a procedure /
function / method. However, particularly arcane bits of code invariably
need commenting in order to facilitate quick comprehension.
Your point about the code expressing things unambiguously is not
actually always true. Yes it is the case that the compilation /
execution system will (except in tha case of non-deterministic code)
have a single execution model. It is however the case that the
programmer / reader of a bit of code can have the wrong undestanding of
that execution model. This is particualrly true for people working with
multiple languages who can inadvertently apply the execution model from
one language onto another.
But that, friends, is the problem with comments. Code is usually hard to read, comments easy. If the comment writer has the wrong model of the code, then the comment will be worse than useless. And when do you read comments? Why, to debug the code they comment (then the comment is almost certainly misleading), or to debug the stuff you are trying to interface to the code they comment (then the comment, like so much documentation, is often misleading).
Of course, writing stuff about code is not pointless. I've done it for a living; I hope it will make me a living once more. But the crude slogans about comments, like the ones about variable names, do a disservice. People who don't understand the code they write (that's all of us) will misdescribe it. Misdescriptions hurt.
I comment my code for myself, usually after a long debugging session with a difficult bit. I write down what the code is intended to do: that is, a sort of specification. That helps me, when I come back in a year's time, to check that I really did think I knew what I was doing. But it doesn't do much more: so often I have to rewrite the comments, because now I understand the code a little better.
And another thing (sorry, I've bottled this up for a long time) related to comments. Program variable names. I was trained, and for a while I trained others, to use great big long names which convey intentions. Names like thedistancetothetrainbehindus or thetimesincewepassedthelastredsignal, instead of names like d and t. When I started getting analytical about programming, I started to read and to write code which used names like f, x and y. A great advantage of conciseness was revealed: you can read the code because (a) it's small, not being bloated with all those big names; (b) you read it for what it is and not what the author was thinking about when they wrote it. Of course there's a need for great long names when references are long distance, over many many pages: but within a page I'm a great user for a long time of f, x and y. I saw the advantages when I saw engineers struggling with proofs in a formal system development tool: the names they were using were much longer than the ones I quoted above, and the problems and proofs were correspondingly difficult to read. Change the long names to short, and the problems became obviously as trivial as they really were.
But to come full circle: would I prefer to read the uncommented or the commented code of a programmer who doesn't know what they are doing? I guess I'd have to say the commented code: but I'd read the comments last, and I'd curse the variable names as I went.
Richard Bornat
