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

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

[Richard Kenner]

    use google? I really find little sense in explaining this; it would be
    other matter if it was something non-trivial, but this is something
    that simply cannot be done in much different way.

It still needs to be documented *in the source code*.

    > There are *very few* comments at all in these
    > files and absolutely no overview of what they are doing.

    Sorry, but there are generally comments every 5-10 lines and I refuse
    to write more.

The issue isn't the *frequency* of the comments but their size and content.
If you "refuse" to write more, than I strongly suggest we refuse to accept
your patches.  GCC is a very large program and needs to be clearly and
carefully documented.

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

[Zdenek Dvorak]

Hello,

>     use google? I really find little sense in explaining this; it would be
>     other matter if it was something non-trivial, but this is something
>     that simply cannot be done in much different way.
> 
> It still needs to be documented *in the source code*.

done

>     > There are *very few* comments at all in these
>     > files and absolutely no overview of what they are doing.
> 
>     Sorry, but there are generally comments every 5-10 lines and I refuse
>     to write more.
> 
> The issue isn't the *frequency* of the comments but their size and content.

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

Zdenek

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

[Joseph S. Myers]

On Fri, 31 Jan 2003, Richard Earnshaw wrote:

> > but here's some general points:
> [snipped]
> 
> These notes should be added to:
> 	http://gcc.gnu.org/codingconventions.html

No they shouldn't, there's nothing GCC-specific about them.  They simply
describe good practice in commenting C code.  Much of this is already
discussed in the GNU Coding Standards, section "Commenting Your Work";
anything that isn't discussed there should go there rather than somewhere
GCC-specific.

-- 
Joseph S. Myers
jsm28@cam.ac.uk

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

[Richard Earnshaw]

> but here's some general points:
[snipped]

These notes should be added to:
	http://gcc.gnu.org/codingconventions.html

R.

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

[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.

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

[Robert Dewar]

> files and absolutely no overview of what they are doing.

It is actually the overview that is most critical in this case.