Re: [RFC] Contributing tree-ssa to mainline

[Geert Bosch <bosch@gnat.com>]

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