This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
Re: "Documentation by paper"
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 :-)