Dwayne Reid wrote:
> I still think that you are missing the point.  The routine is
> completely documented in terms of how to use it and what the expected
> outputs are.  Treat the block of code as a 'canned routine' if you
> need to.

But source was provided, which gives us another point to judge the code and
its author by.  The code uses some tricks and cleverness to be extra
compact.  This comes at the cost of clarity.  The author obviously thought
about the clever tricks carefully at some point.  Not writing down those
details at the time says a great deal about the author.  Later defending not
doing it says a lot too.

Some people don't get what comments are for.  Andrew may be very good at
writing highly optimized PIC code, but if he doesn't understand why such
code needs to be especially well documented, then I don't want anything to
do with stuff he's written and I advise others, especially newbies, to stay
clear too.  If someone working for me produced that code, he'd get a serious
talking to.  If he came back with the attitude of trying to explain why the
inline documentation wasn't necessary, he wouldn't last long here, perhaps
only seconds.

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.  The example in question fails to the point of
casting doubt on other products of the same author.


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.
-- 
http://www.piclist.com PIC/SX FAQ & list archive
View/change your membership options at
http://mailman.mit.edu/mailman/listinfo/piclist