From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 30349 invoked by alias); 25 Jun 2007 21:06:41 -0000 Received: (qmail 30341 invoked by uid 22791); 25 Jun 2007 21:06:41 -0000 X-Spam-Check-By: sourceware.org Received: from rock.gnat.com (HELO rock.gnat.com) (205.232.38.15) by sourceware.org (qpsmtpd/0.31) with ESMTP; Mon, 25 Jun 2007 21:06:38 +0000 Received: from localhost (localhost.localdomain [127.0.0.1]) by filtered-rock.gnat.com (Postfix) with ESMTP id C4C7E2A98F9; Mon, 25 Jun 2007 17:06:36 -0400 (EDT) Received: from rock.gnat.com ([127.0.0.1]) by localhost (rock.gnat.com [127.0.0.1]) (amavisd-new, port 10024) with LMTP id lk4RELdzCJo3; Mon, 25 Jun 2007 17:06:36 -0400 (EDT) Received: from [127.0.0.1] (nile.gnat.com [205.232.38.5]) by rock.gnat.com (Postfix) with ESMTP id 467F02A98E6; Mon, 25 Jun 2007 17:06:36 -0400 (EDT) Message-ID: <46802E5C.4090408@adacore.com> Date: Mon, 25 Jun 2007 21:06:00 -0000 From: Robert Dewar User-Agent: Thunderbird 1.5.0.12 (Windows/20070509) MIME-Version: 1.0 To: Robert Dewar CC: Eli Zaretskii , pkoning@equallogic.com, jimb@codesourcery.com, eager@eagercon.com, stanshebs@earthlink.net, gdb@sources.redhat.com Subject: Re: What's an annex? stratum? References: <467D5FEF.7010900@eagercon.com> <467D6D1F.7090507@earthlink.net> <467D6FB8.4080909@eagercon.com> <468009EA.4040504@eagercon.com> <18048.5444.903092.843811@pkoning.equallogic.com> <20070625193135.GA6391@caradoc.them.org> <4680199F.7020906@adacore.com> <46802911.7070209@adacore.com> <46802D87.3040509@adacore.com> In-Reply-To: <46802D87.3040509@adacore.com> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit 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/msg00275.txt.bz2 Robert Dewar wrote: > Eli Zaretskii wrote: > >> You aren't familiar with my standards of ``adequate comments''. > > Well then you probably are not familiar with the GNAT front end :-) > > To me, code that is lacking in full documentation is unacceptable > (yes, most code around meets that criterion). Just to be clearer, I mean most code around is indeed lacking in full documentation. In particular, things that are often missing are global documentation (yes, this can be in separate documents if they are kept up to date). local documentation that does NOT depend on guessing what variable names mean, or reading what code does. In particular documentation about what you did NOT do and why not (that's something you definitely cannot deduce from the code, but is often very important).