From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 14545 invoked by alias); 27 Jun 2007 00:32:32 -0000 Received: (qmail 14537 invoked by uid 22791); 27 Jun 2007 00:32:32 -0000 X-Spam-Check-By: sourceware.org Received: from mail.codesourcery.com (HELO mail.codesourcery.com) (65.74.133.4) by sourceware.org (qpsmtpd/0.31) with ESMTP; Wed, 27 Jun 2007 00:32:30 +0000 Received: (qmail 18718 invoked from network); 27 Jun 2007 00:32:28 -0000 Received: from unknown (HELO localhost) (jimb@127.0.0.2) by mail.codesourcery.com with ESMTPA; 27 Jun 2007 00:32:28 -0000 To: Robert Dewar Cc: Joel Brobecker , Markus Deuling , Eli Zaretskii , pkoning@equallogic.com, eager@eagercon.com, stanshebs@earthlink.net, gdb@sources.redhat.com Subject: Re: What's an annex? stratum? References: <468009EA.4040504@eagercon.com> <18048.5444.903092.843811@pkoning.equallogic.com> <20070625193135.GA6391@caradoc.them.org> <4680199F.7020906@adacore.com> <46815BC2.9070204@de.ibm.com> <4681A073.5040209@adacore.com> <20070626234056.GZ3706@adacore.com> <4681A48E.8060201@adacore.com> From: Jim Blandy Date: Wed, 27 Jun 2007 00:32:00 -0000 In-Reply-To: <4681A48E.8060201@adacore.com> (Robert Dewar's message of "Tue, 26 Jun 2007 19:43:10 -0400") Message-ID: User-Agent: Gnus/5.11 (Gnus v5.11) Emacs/22.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-IsSubscribed: yes Mailing-List: contact gdb-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-owner@sourceware.org X-SW-Source: 2007-06/txt/msg00329.txt.bz2 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. 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.