This is the mail archive of the mailing list for the GCC project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [RFC] Contributing tree-ssa to mainline

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.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]