From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 25414 invoked by alias); 4 Feb 2004 13:48:40 -0000 Mailing-List: contact gcc-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Archive: List-Post: List-Help: Sender: gcc-owner@gcc.gnu.org Received: (qmail 25354 invoked from network); 4 Feb 2004 13:48:38 -0000 Received: from unknown (HELO nile.gnat.com) (205.232.38.5) by sources.redhat.com with SMTP; 4 Feb 2004 13:48:38 -0000 Received: from localhost (localhost [127.0.0.1]) by nile.gnat.com (Postfix) with ESMTP id 44227F2F15; Wed, 4 Feb 2004 08:48:38 -0500 (EST) Received: from nile.gnat.com ([127.0.0.1]) by localhost (nile.gnat.com [127.0.0.1]) (amavisd-new, port 10024) with LMTP id 26322-01-9; Wed, 4 Feb 2004 08:48:38 -0500 (EST) Received: from gnat.com (hoosic.gnat.com [205.232.38.102]) by nile.gnat.com (Postfix) with ESMTP id DD9DCF2D83; Wed, 4 Feb 2004 08:48:37 -0500 (EST) Message-ID: <4020F7EF.8000406@gnat.com> Date: Wed, 04 Feb 2004 13:48:00 -0000 From: Robert Dewar User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.6) Gecko/20040113 MIME-Version: 1.0 To: Dale Johannesen Cc: gcc@gcc.gnu.org, Richard Kenner , s.bosscher@student.tudelft.nl Subject: Re: "Documentation by paper" References: <10402031630.AA22094@vlsi1.ultra.nyu.edu> <40201B2B.4090101@gnat.com> In-Reply-To: Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit X-Virus-Scanned: by amavisd-new at nile.gnat.com X-SW-Source: 2004-02/txt/msg00233.txt.bz2 Dale Johannesen wrote: > While I have no wish to discourage anyone from improving the > documentation (and I'm curious how many people on this thread > are actually doing so), I think you exaggerate the dangers. > "block" means different things to FE people and BE people, > and there are places where it isn't obvious which is meant until > you grovel through the code a bit, and we've all been coping with > it for years. I am a bit flabbergasted by this reply, which essentially says "we don't need accurate documentation, because we have managed in the past by "grovel[ing] through code a bit". The push for good documentation comes from a viewpoint that this kind of groveling is highly undesirable. Yes, you can program everything in absolute binary machine language with no comments at all if you have to, but the fact that you can manage with an unacceptable state of affairs is not a good argument for continuing it. The particular example I gave (the question of whether A dominates itself) is exactly the sort of thing that can cause subtle bugs in code, especially in the *maintenance* of such code. The original author may have absolutely known the answer to this question (and may well, indoctrinated by some particular compiler course or book, not even know there *is* a question, after all several correspondents in this thread seemed to think the definition of dominator was universal). But a maintenance programmer who has taken a different compiler course or read a different compiler book, may assume the other definition, and that can indeed result in confusion and subtle bugs. The case of a dominator is actually a very nice one. This is a simple concept that can be explained in a couple of short sentences. Why on EARTH would anyone object to including such a definition in the code? I find such objection inexplicable. In the GNAT world, we regard it as a bug if someone coming to read the code new finds the comments incomplete. We file and fix bug reports of this kind like any other bug report, since we regard correct and complete documentation as being as important as correct and complete code. I am sure we still have lots of such bugs in the GNAT code (some of them are marked with ??? in the sources, often by me :-) Feel free to point out others :-)