This is the mail archive of the mailing list for the GDB project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: What's an annex? stratum?

Jim Blandy wrote:
Robert Dewar <> 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.

I find the same thing, and even more these days, I find I can't rely on my memory so well, so if I come back to code I wrote 6 months ago, I need the documentation as much as anyone :-)

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.

certainly fair enough.

One thing that I have found helpful is to ask newcomers to report
as bugs cases in which the code is not clear, and then when the
explanations are given, or the detective work completed, help
write the documentation they found missing.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]