Re: Hungarian notation

[willer@carolian.com (Steve Willer)]

dewar@cs.nyu.edu (Robert Dewar) wrote:

>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. 

As with everything, comments can hurt or they can help. If you require
the developer to sprinkle comments all over their code, they will almost
certainly get out of date.

I prefer to concentrate on writing code that's as clear and
self-documenting as possible, inserting comments in places where it is
necessary to give the "big picture" of what I'm doing. I've found it
counterproductive to create comments like this, for example:

Bar(vector<Foo> &vFoo) {
   // for each Foo...
   for_iter(vFoo, FooIterator) {
      // run some calculations on it
      DoSomeStuff(*iter);
   }
}

(Please excuse my for_iter macro; I'm very proud of my new creation and
I like to use it whenever possible)

The above code is an example of the "write comments that indicate the
structure of your code" form of commenting that I played around with for
a while. I found it unwieldy. I also decided that if your code is so
complicated that you have to comment _every step_, then you need to
rethink your design.

But as I noted earlier, there are times when comments are very good for
giving context to an unfortunate hack you had to pull together, or a
particularly complicated algorithm. I tend to write those in "essay"
style, sometimes making them 5-9 lines of comments.

I also write up comments to subdivide logical sections of medium-length
functions (I completely disallow longer functions)...perhaps something
like:

bool Go() {
   // initialize the internal View
   ...

   // generate the output
   ...

   // cleanup
   ...
}

...but that's as far as I go. Is that less than what you like, or is it
what you're talking about?

>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.

I wish teachers would also stress the need for writing code that's as
self-documenting as possible. If it's possible to make code very clear
without comments, I feel that's much more valuable than adding 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. 

Lots of those. :-)

>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.

Part of the reason I try to keep it at a minimum.