Olin, this is the best explanation I've ever seen on the importance of
commenting code. Well done!

--Bob


At 08:31 AM 8/16/2003 -0400, you wrote:
>Jim Tellier wrote:
> > The Importance of commented code *cannot* be disputed.  Period.
> > HOWEVER, I
> > *always* take issue with the concept of "commenting as you write it"!
> > IMHO, it is an order of magnitude more useful to comment it *after* it
> > has been debugged and Proven.
>
>I strongly disagree with this.  Show me someone who comments code "later",
>and I'll show you lots of code that hasn't been touched in a long time
>still waiting for "later".  I also suspect that much of this code will
>have hidden bugs.
>
>To me, comments are in integral part of the development process.  My
>overall productivity would be a lot less if I was not allowed to comment
>code until after the project is working, and I'd be making stupid mistakes
>along the way.
>
>How many times have you had a case where there could be several ways to
>express the same value in a global variable?  Without documenting the
>format where it is defined, you could easily assume a different format
>when you're writing a module that uses the variable a few days after
>writing the module that sets it.  The same principle holds for any
>interface between two separate sections of code, like how a subroutine is
>called.  Do you really want to have to look thru the executable code of a
>subroutine to figure out exactly how a parameter is passed to it and what
>the format needs to be?
>
>Think of it another way.  As you are writing the executable code you are
>as close to the details as you're going to get for that code.  There are
>tradeoffs and other low level decisions you are juggling in your mind as
>you write that code.  That's the time to write them down, if for no other
>reason so that you don't have to try to remember them as you go to the
>next chunk of code or module.  It's like keeping a design notebook, except
>that you don't write it in a separate place.  That's much better since it
>will more likely be kept up to date and will always be available along
>with the designed product itself.
>
> > When someone (e.g. neophyte, expert,
> > whatever) writes & comments a piece of code, discovers that it doesn't
> > work, then asks buddy/coworker/newsgroup/FAE/PICLIST/his mama or
> > whomever, to "please take a look at this and see if you can give me a
> > clue as to why it doesn't do what I expect".... I've seen many times
> > that the comments (describing the INTENT of the programmer) simply
> > obfuscate the actual problem manifested in the CODE: i.e., the comments
> > tell you what the code is *supposed* to do, thus adding a  certain
> > "credibility factor" to the actual code statements before the reviewer.
>
>You are making the mistake I see too often, which is thinking of comments
>as something "extra" that can be added to code like a little extra salt to
>soup to make it just right.  Comments are an integral and essential part
>of the code.  Any review process therefore needs to review the comments as
>much as the executable part of the code.  I suppose sloppy reviewers could
>check the comments more than the executable part of the code, but that
>only shows that reviewing code is a skill, and there are bad reviewers
>just like there are bad programmers.
>
>
>*****************************************************************
>Embed Inc, embedded system specialists in Littleton Massachusetts
>(978) 742-9014, http://www.embedinc.com
>
>--
>http://www.piclist.com hint: The list server can filter out subtopics
>(like ads or off topics) for you. See http://www.piclist.com/#topics

--------------
Bob Axtell
PIC Hardware & Firmware Dev
Tucson, AZ
1-512-219-2363

--
http://www.piclist.com hint: The list server can filter out subtopics
(like ads or off topics) for you. See http://www.piclist.com/#topics