Olin Lathrop wrote:

> This is all just another part of what I've been saying here for a long
> time: Neatness and clarity count.  I have often observed a strong
> correlation between sloppiness and bad design.  Being able to take
> the last few words or cycles out of a algorithm can be useful and
> requires skill and knowledge, but it's a rather small part of good
> design.  (In fact a lot of the time it's bad design because the wrong
> tradeoffs were made, but this is not the issue here.)  Using clear
> thinking and producing good documentation are bigger parts of good
> design.  

I second this. In a professional setting, an average programmer (average
for the given venue) should be able to read through code without having
to scratch her had and going back and forward trying to find out why
something was done the way it was done. If this happens, IME it is
always a strong indicator that there's a bad structure or a lack of
comments.

Sometimes bad APIs or efficiency requirements impose a bad structure,
and in this case the comment are something that can save the maintenance
programmer who has to touch that code from making a mistake. Most
programmers are surprised time and again how many of the details of what
they thought when they wrote some code they forget in how short a
timeframe. Much of this belongs in comments.

So as much as the art of writing the actual functional code is
important, for the complete picture the art of writing the right amount
of comments with the right content is almost as important -- not
immediately, but in the long run. But, of course, what the "right amount
of comments with the right content" is is a matter of individual
judgment, and different people will reach different conclusions. 

It may sound odd to call a marvelously optimized and perfectly working
gem of code "bad", but in certain contexts that may be a valid (even
though not the only possible) judgment.

Gerhard
-- 
http://www.piclist.com PIC/SX FAQ & list archive
View/change your membership options at
http://mailman.mit.edu/mailman/listinfo/piclist