Re: Hungarian notation

[tangent@cyberport.com (Warren Young)]

ENGR@GSSI.MV.COM (Michael Furman) wrote:

>>My own experience with some of my co-workers is that typing skills are
>>very important as well. If the programmer has to hunt-and-peck at 20
>>words a minute, they would be inclined to write minimal comments, log
>>messages, etc., using abbreviations that nobody except themselves can
>>understand. Plus, it promotes the naming of variables like "var",
>>"evnt", etc.
>
>   Interesting that my experiance is exectly opposite. Almost all programmer
>I worked with or watched their work, who were typing fast produced poor
>code (may be with comments, but often redundant or meaningless). I believe
>they (usually) just don't have enough time to think.

I dunno, I think there's truth in both statements.  From my own
experience, my code has become more verbose over the years as my
typing speed has increased.  Some of this is just that I know better
now, but some of it is that it's much less painful to be verbose.  

On the other hand, I know a guy at work who hunts and pecks (often
with only one hand!) and he's the most verbose coder I know.  I think
he's a bit of an exception, though, because he doesn't write much
code, so he probably just wants to make his reimmersion time as low as
possible.  For what it's worth, he also prefers writing everything in
a single module, so he always knows where everything's at.  B-)

I think that there are two basic types of programmers, as far as this
goes, and that people move from the first to the second with training
or experience.  The first group is those who think that getting the
program done as fast as possible is a function of the amount of code
written per hour.  The second is those who know all of the steps
necessary to turn out a good, solid product.  Their current "type" and
their typing speed together influence the programmer's documentation
skills.  So, for your approval, here are some quick summaries of the
type combinations:

Slow typists who want to turn out a lot of code are terse.  I think a
lot of newbies fall into this category.

Slow typists who know how to document well try to write the code
correctly the first time.  (They know they are slow, so they take the
time to think things through before coding, so they don't have to
re-write as much.)  Programmers originally trained as engineers
probably fall into this category at first; they're not good typists
because they don't have the practice, but they know how to write good
supporting documentation because that's part of an engineer's
training.

Fast typists who don't know how to document well (or don't care)
simply turn out many, many lines of rubbish.  They may get the job
done, though, because their speed lets them re-write several times in
the time it takes a slow programmer to do it once.  Again, this
exemplifies many newbies, except that these ones can type.

Fast typists who know how to document well force themselves to take
the time to think things over as they go along.  Comments help because
they force a change of pace, and they force a re-think of what's going
on.  Hungarian Notation probably helps, too, because it can act as a
governor on the typist's speed, since they often have to take the time
to think the prefixes through before continuing.

>   I personally sometimes write comments just to think one more time trough
>just written code (or code I'm going to write). It helps find bugs (even
>in design) and sometimes find better solution. 

Ditto, wholeheartedly.  I think this works because a good commenter is
trying to explain the following bit of code (or mention what isn't
obvious).  In doing so, you are casting yourself in the role of a
teacher, probably to someone who knows less about this bit of code
than you do.  The result is that it forces you to rethink the code.  I
find that if I have to use a 10-line comment to explain four lines of
code, one of the two (the code or the comment) is probably too
complex.  I usually re-write one or the other, and the whole is
improved as a result.

As for your "design" comment, I also agree.  Comments should be one
level above the code -- the design level, in other words.  (By the by,
this is why the people who argue that the code alone is sufficient
documentation are wrong, IMO.)  So, you're re-doing the design as you
write the code that implements that design.  If you can write the code
and comments easily, the design is probably correct.  If either one
becomes a problem, it's a hint that the design may be flawed.

I find that comments are really good at throwing light on over-complex
intercommunications and interdependencies.  The comments document
what's going on at the level above the actual code, which includes the
intercommunications.  Well, if you find yourself rambling on in a
comment about how this object communicates with the others it needs to
communicate with to do its work and about the special rules involved,
it's probably a clue that something's too complex.

All of that in a nutshell: Comments reflect something of the code and
of the coder.  You can learn to use those comments not only for
documentation, but as a potential problem indicator.

= Warren -- http://www.cyberport.com/~tangent