>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

>> Olin Lathrop wrote:
>
> No, I didn't.  This was written by Dave Tweed:
>
>>> Even in those rare situations where every line requires
>>> a comment, I firmly believe that the comments and code
>>> should be on separate lines.
>
>This part I did write:
>
>>> I guess we'll just have to disagree on this one...
>>> Did you feel the extensive end of line comments were more of an
>>> annoyance or a help in understanding the code in the first place?

> > But of course even a seasoned pro might get stung during a
> > port from 16F to
> > 18F by the fact that on the 18F INCF does affect the carry.
> > (This is one of
> > the few poor decisions mChip made on the 18F, IMHO).
>
> You halfway got me there, but actually it (again) proves my point: know
> your audience before you write comments (and know the intended audience
> before you judge someone else's comments). And this applies to all
> writing, not just comments. And of course it gets problematic when your
> adience is diverse and/or unknown, like when posting on this list ;)
>