Re: An issue for the SC: horrible documentation quality of GCC

[Scott Robert Ladd <coyote at coyotegulch dot com>]

Richard Kenner wrote:
> I want to repeat what I just said in a separate message: the amount of
> totally undocumented code in GCC is approaching very troublesome levels.
> There are who areas of the compler in which nobody but their author can
> work due to a complete lack of any high-level documentation.

Totally agreed. One major impediment to my working on GCC is the lack of
accurate and complete documentation, either external or embedded in the
code.

> The local_cprop_* functions in gcse are a very good case in point.
>
> There is no comment anywhere that I can find of the form "This phase performs
> the ABC optimization by doing the following algorithm.  This optimization
> is useful because XYZ and does not duplicate a similar optimization in QQQ
> because of BAR."

Exactly. For example, I would very much like to add automatic
vectorization to GCC; this is the one area where GCC's performance falls
short of its commercial competitors for high-performance applications. I
have a vague notion of where to start, after studying the code -- but I
hesitite to start hacking on such an important project as GCC without a
clear sense of how the code works.

> There's no point in trying to understand how we got to this appalling state
> of affairs, but we do need to decide how to proceed from now.  My suggestion
> is the following:
>
> (1) Do not allow any further patches to the compiler that do not have proper
> documentation.

Enforcing such a dictate would be problematic at best. You'll find
resistance from the "we need this now" crowd, which seems to lead a
robust life in both free and commercial products.

Even for writers like myself, documenting code is less enjoyable than
creating it -- yet when delivering code to a client, I document every
line thoroughly, because that is the "right" thing to do. I don't think
many "free" developers treat "free" software projects as they would a
commercial "business" product -- and therein lies the lack of motivation
for documenting code.

> (2) Remove any parts of the compiler for which documentation is not supplied
> by the 3.4 release.

Not feasible, given that this would leave us with a non-working compiler. :)

That said, I've expressed interest in the past in working on the gcc
documentation; however, my inquiries to the community about specific
issues (i.e., what the heck does this do?) tend to fall on deaf ears.

Quality documentation for GCC will result from a community concensus
that documentation is important, and a combined effort to describe the
arcane aspects of the code base. The big question is: How do we rally
that support?

> It is very clear that the approach of supplying documentation later
> does not work.

Most certainly true.

--
Scott Robert Ladd
Coyote Gulch Productions (http://www.coyotegulch.com)
Professional programming for science and engineering;
Interesting and unusual bits of very free code.