Re: Examples in Docs, was Re: Escape Sequences in Strings

["Peter Richtmyer" <pmr@efortress.com>]

<mark_lundquist@my-deja.com> wrote in message
news:94299p$8dd$1@nnrp1.deja.com...
> In article <940f9j$nj2$1@nnrp1.deja.com>,
>   peter_richtmyer@my-deja.com wrote:
> > [...]
> > Putting examples in documents is
> > somewhat similar to putting comments in code. It
> > is not necessary, but it sure makes it easier for
> > the readers.
>
> Of course you don't mean that comments are unnecessary in program text,
> only that they do not affect the function :-)
>
Actually, I did mean they are *unnecessary*, meaning *not needed*.

They are certainly not required by the compiler. With respect to the human
reader,
given enough time, and given access to the requirements, design specs, PDl,
interface
specs,  other docs, other people, etc,  the program comments are *not
needed*.
Please don't misunderstand, I tend to be a *comment freak*, writing more
lines of
comments than code in the programs that I write. I tend to attach words like
*lazy*, *discourteous*, and *unprofessional* to programmers I work with who
do not adequately comment our code. Though *clue-less* might pertain too.

I used the word *our* above very intentionally too. I am talking about our
team
and our company. No one person owns the code at work. I take pride in my
code. But not sole possession.
>
>
In another sub-thread of this discussion, someone stated that document
examples
and program comments are not *analogous*. I agree. I intentionally avoided
the
use of the word *analogy*, instead weasle-wording it with the phrase
*somewhat similar* (see above).

Examples and comments are somewhat similar in that they both make it easier
to
understand what I am reading (document or program) . They can also make it
easier to perform what is quite often the next step, i.e. to create or
modify some
code.  And, of course, the comments.  :-)

Peter

P.S.  Why do I keep using * instead of "  ?     :-)