Re: Hungarian notation

[dewar@cs.nyu.edu (Robert Dewar)]

Peter Moylan wrote:

.Richard A. O'Keefe (ok@goanna.cs.rmit.EDU.AU) wrote:
.>nreitzel@lonestar.jpl.utsa.edu (Norman L. Reitzel   ) writes:
.>>As for serious code, I've ported million line projects for a telephone
.>>company, and managed projects that produced twice that.  The key to
.>>maintainability is defensive programming, and ADEQUATE BLOCK COMMENTS.
.>>Any chunk of code that does not contain info about what it does and how
.>>it does it is an error waiting to happen.  The rude concept of
.>>"self-documenting" code belongs in an ivory tower with those who teach,
.>>not in the trenches with those of us who DO.
.
.>Those of us who teach struggle hard to persuade students to write
.>good comments.
.
.I don't know where this myth comes from.  In my 20+ years in
.academia, I have NEVER met a software teacher who considered
.uncommented code to be acceptable.  Practically everyone tries
.to get across the message "write the comments first, and then
.the code".

In fact the anti-comment attitude comes from the trenches rather than from
the ivory tower. The main argument seems to be that since no one can ever
manage to maintain comments properly, it is better to have no comments, or
at least to minimize comments. I strongly disagree, and feel that it is
better still to keep the comments up to date. A bad comment is a bug, as
serious as any other latent bug in the "real" code, and programmers have
to start thinking that way.

Yes of course it is hard to keep comments up to date -- there are many
hard things about programming, this is one of them.

To see the anti-comment view, look at section 3.3 of AQ&S (one of the few
sections of this document that I am not fond of). It starts by saying

  "Comments in source text are a controversial issue"  (!)

and then goes on to present what supposedly is a balanced discussion on this
issue that to my taste is far too anti-comment. Some excerpts:

  "There are argments both for and against the view that comments
   enhance readability"

  "Comments should be minimized"

  "source text should .. so that little additional commentary is needed"

There is nothing exactly *wrong* with any of these statements, but the
general tone adds up to me to be far too anti-comment.

As Peter says, most teachers stress comments. I certainly give zero to any
assignment that is uncommented, and take marks off for incompetent, incorrect
or annoyingly useless ("increment I") comments.

In practice many programmers are incapable of writing coherent English, so
they have no chance in any case of writing useful comments, and many other
programmers are lazy and don't feel like commenting code. Maintenance
programmers are often still more lazy and try to change the minimum number
of characters to make a problem go away, and of course this does not include
changing comments.

To me good comments are essential, the code can only tell you what it does
and how at a level of abstraction matching the code. Good comments tell you:

   a) what the code is doing at a higher level of abstraction
   b) why you did what you did
   c) why you didn't do something else

obviously code cannot be self-documenting in these three aspects.

Of course I agree that incorrect or inconsistent or out-of-date comments
are a menace, but that's an argument for making sure the comments are
correct, consistent and up-to-date, not for eliminating them!

Incidentally, I also follow Peter's rule of never helping with uncommented
code, and in fact if students show me uncommented code, I take marks off
the assignment no matter WHAT is eventually handed in, since I insist
that coments must be written as part of the process of coding, not as an
after-thought. In practice, this works very well, since I use email to
give continuous feedback to students on early versions of their assignments,
and they find this feedback valuable enough to be worth the nuisance of
commenting their code!