Re: Hungarian notation

[willer@carolian.com (Steve Willer)]

kcline@sun132.spd.dsccc.com (Kevin Cline) wrote:

>This is a subject that seems to be largely ignored in undergraduate
>curricula.  The developers that do know how to comment seem to have
>learned by example.

This is a very interesting point, and one that my own experience as a
former student supports. Although my teachers did require that the code
be commented, they never made a reasonable attempt at teaching us what
kind of comments should be created, why they're important, caveats, etc.

I've had a continuing discussion via e-mail on this topic, and I thought
I wrote a reasonably good letter today that perhaps gets into more
specifics. I'll reproduce it here:

---------------------------------------------------------------------
>Note that everyone agrees that silly comments that just repeat what the
>code is doing are useless, but on the other hand, I find the idea of
>self-documenting code to be largely bogus. The most code can tell you
>is what it does and how it does it (true -- much poorly written code
>can't even tell you that).

Well, let's say for the sake of argument that it _is_ possible to have
fairly good self-documenting code. Would you agree that self-documenting
code would be more valuable, from a maintenance perspective, than any
comments within the functions?

You see, I believe strongly that it _is_ possible to make code clear
without resorting to side commentary. So I strive to achieve this
whenever possible, and I find that a good notation system helps
tremendously.

Let me give a quick analogy. If you're watching a movie and you just
don't understand what's going on, if you had a choice between someone
whispering explanations in your ear and having the movie make sense in
the first place, you would probably choose the latter, right? I find
that comments sprinkled throughout the code break the "flow" and
therefore damage the ability of the maintainer to understand the way the
code works without having to mentally step through every line of code.

>BUT! it can't tell you the why, and even less the why not (why you did not
>do something else). Furthermore, properly written comments are at a level
>of abstraction that is definitely above the level of the code, and this
>can make it far easier to follow the intent and shape of code without
>having to read the code itself (which is at a more detailed level, and 
>therefore takes more effort to read).

Part of the problem is that there are so many different types of
comments, it's difficult to have a good discussion about them without
recognizing the different types.

In particular, there are:

1. design documentation (I consider this to be related to comments)
2. "headers" at the top of functions, indicating what the function does,
   what the parameters mean, etc.
3. "procedural" comments, which are of the "literate programming"
   variety, like the example I gave earlier

[Note: this point refers to comments that are created to show program
structure before the code is written, which is suggested in at least one
book that I've read. An example might be:
   // for every node
      // tell the node to output its iteration
   // tell the user that we're done
]

4. "low-level overview" comments, which indicate what is going to
   be done in a 5-15 line segment. They can also serve to separate
   a function into multiple higher-level segments.
5. "hack" comments, which document a weird hack or bizarre form of
   algorithm that you are employing

Now, your comment about the useless comments seems to be about the "bad"
form of #3. My own personal experience is that I don't get much use out
of #3 at all, despite the fact that a number of books seem to recommend
this practice. My comment at the top of this letter is in fact about #3
specifically.

I personally feel that #1 and #2 are absolutely required for any
software that will be maintained by a different person or a few months
down the road (i.e. all software). I also feel that #5 is very
important, partly so maintainers can understand why the hack was put in,
but also perhaps more importantly to be sure that they don't undo the
hack (probably every developer has at least once looked in disgust at a
hack and "cleaned it up," only to discover later that there was a good
reason for it being there).

Now, #4, I tend to feel is optional. I try to limit my use of #4 to
places where the functions are long or complicated, but since I'm a C++
programmer, one of the design principles I try to live by is "write
simple functions". Consequently, #4 isn't needed very much in my code.
This is an example where I feel it's much more important to concentrate
on design principles than commenting principles.

I guess my biggest objection to the "comments are God" type of attitude
I see sometimes is that there are more important things to be done, like
fixing a bad design. I don't want to see comments being used to cover up
a bad design or bad code.