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

[mark_lundquist@my-deja.com]

In article <J_e96.5326$DI.58950@e420r-atl1.usenetserver.com>,
  "Peter Richtmyer" <pmr@efortress.com> wrote:
> <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*.

So strictly speaking, it's not comments that are necessary (for
understandability), but documentation...

I almost said that in another post, but I didn't want to cloud the
issue!  Bad call, I guess... :-)

I think the idea of embedded hyperlinks in comments to navigate out to
supporting documentation of the kind you mention could really be
worthwhile (DING!  Cue for Bob-Leif-XML-followup :-) :-) :-)

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

Maybe some kind of pinky finger deformity? :-)

Cheers,
Mark


Sent via Deja.com
http://www.deja.com/