Re: [PATCH] rtlopt branch merge part 5 -- loop unswitching

[kenner at vlsi1 dot ultra dot nyu dot edu (Richard Kenner)]

    Can you give some more concrete suggestion what should be improved on
    them? I tried to mention everything important already.

I sent some just to you and the gcc-patches list, but here's some general
points:

(1) The overview in front of the file should describe the optimization you
are trying to do and, in general terms, how you are doing it, though in this
case I agree that's somewhat obvious.  If there's a paper describing this
optimization, reference it.  If the terminology between the paper and GCC is
different, contrast them.  These are the most important comments in the file
and every other comment can be viewed as an expansion of these.

(2) For each function, the reader should be able to completely understand
what the function is the comments in front of the function.  Those comments
should say what it's supposed to do and are the second most important
comments in the file.  The code and comments *inside* the function say *how*
the function is implemented, as opposed to what it's *supposed* to do.
Conceptually, the header comments represent the *specification* of the
function, and hence your *intent*, and what's inside represent how you
implemented that intent.  These two may not be the same and that's not
necessarily a bug because you may know that something doesn't have to be done
in a particular case.

(3) The comments inside a function are the least important, but still serve
valid purposes.  However, if they are just a few short words that are nothing
more than a translation of the C into English, all they do is add clutter and
are best removed.

Basically the purpose of these comments is to say *how* and, most
importantly, *why* the code in the function implements its specification (and
is why those outside comments are the most critical).  For example, if the
function is described as doing a number of different things, it's valuable to
use comments to delimit the code (if applicable) into the part that's
implementing each of those things.  If it's not obvious how a piece of the
implementation corresponds to the specification, the comments should explain
that correspondance.  They should also explain any shortcuts taken in the
function and why they are valid.

I hope this clarifies things.