From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 14690 invoked by alias); 20 Jan 2004 03:12:50 -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 14679 invoked from network); 20 Jan 2004 03:12:49 -0000 Received: from unknown (HELO nile.gnat.com) (205.232.38.5) by sources.redhat.com with SMTP; 20 Jan 2004 03:12:49 -0000 Received: from [216.220.103.156] (unknown [216.220.103.156]) by nile.gnat.com (Postfix) with ESMTP id 51E8FF2DFD; Mon, 19 Jan 2004 22:12:49 -0500 (EST) In-Reply-To: <476C5192-4AD9-11D8-8DB8-000A95DA505C@dberlin.org> References: <10401170324.AA15949@vlsi1.ultra.nyu.edu> <20040119153026.A21678@synopsys.com> <476C5192-4AD9-11D8-8DB8-000A95DA505C@dberlin.org> Mime-Version: 1.0 (Apple Message framework v609) Content-Type: text/plain; charset=US-ASCII; format=flowed Message-Id: <8DCDA992-4AF6-11D8-AE43-000A959A128E@gnat.com> Content-Transfer-Encoding: 7bit Cc: Joe Buck , gcc@gcc.gnu.org, s.bosscher@student.tudelft.nl, Richard Kenner From: Geert Bosch Subject: Re: [RFC] Contributing tree-ssa to mainline Date: Tue, 20 Jan 2004 03:12:00 -0000 To: Daniel Berlin X-SW-Source: 2004-01/txt/msg01434.txt.bz2 On Jan 19, 2004, at 18:43, Daniel Berlin wrote: > Anyway, It would be more productive if we were to try to concentrate > on a specific set of merge criteria for tree-ssa, than continue to > discuss the benefits or disadvantages of it (since it seems clear the > overwhelming number of people think it has great benefit already) The single biggest issue is documentation. As you say, there are thirty optimization passes. That means that there should be thirty descriptions of these passes: specify what the necessary preconditions are before running the pass (what information needs to be up-to-date etc), what invariants are maintained, what transformations the pass performs, what transformations are not done and why (like other pass does xyz), and what postconditions hold. Also include references to literature where appropriate, including deviations from the described algorithms as well as pitfalls encountered during implementation. Only comments can describe why certain paths have not been taken. All data structures need documentation, statements about initialization and invariants. Every function needs a comment describing its effects at a sufficiently high level, including precise meaning of all formal parameters and effects on global data structures. As explained before, one of the main goals of tree-ssa is to improve maintainability of the compiler by moving to more standard and easy to modify algorithms instead of organically grown intricate webs of functionality. This argument for change only holds water if the replacements algorithms are well-documented. In a way it is worse to have newly written poorly documented code, than similar code that has been around for ages. So I would like to push for strict standards for documentation. All new code must meet the documentation standards *before* merging. Also, any old code that may be affected by the changes needs to be reviewed and stale comments need to be updated. In my opinion everything else is secondary. -Geert