Re: What's an annex? stratum?

[Jim Blandy <jimb at codesourcery dot com>]

Robert Dewar <dewar@adacore.com> writes:
> It is hard to read into this a viewpoint that says that time spent on
> the internals documentation is OK if it is in the source files, but not
> if it is in separate files.

You're right; this doesn't make sense as written.

I write the comments in the code before I write the code, because I've
found that the effort of trying to explain what I'm about to try to do
helps clarify my own understanding a great deal.  For me, at least, it
makes enough of a difference that I'm sure I come out ahead, if you
include debugging time.

In other words, if the internals documentation is written before the
code, then, for me, it is a worthwhile investment.  In that case, I do
believe that writing that documentation brings the completion date
closer, and I write it.  I don't know whether other contributors need
this particular crutch; I'm pretty sure some don't.

The only other time I write explanations is when someone asks for
help; here, again, the investment is worthwhile, because someone is
about to go off and write some code, and I can bring their completion
date closer.  Most of what I've contributed to gdbint.texinfo got in
there because Eli liked something I'd written on the mailing list and
asked me to put it there.

Documenting other code after it's designed and written doesn't have
either of these benefits.

I hate arguing against having clear explanations that make the system
transparent to all comers.  Who wants to be the party pooper?  I
brought up the well-commented code I have written as proof that I do
value quality and clarity, not specifically as evidence for or against
internals documentation.  It happens to be evidence for, but only in
specific circumstances.