This is the mail archive of the gcc-patches@gcc.gnu.org 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: patch: morpho ms1-elf support


> I think that's a hard argument to make.

I haven't fully convinced myself yet ;-)

> I know people make it, and I'm familiar with the many variations,
> but the cases where documentation is actively harmful are pretty few
> and far between.  This argument is certainly made more often by
> people who have to write documentation than people who are reading
> it.

My concern is that the people reading it won't realize the problem.
If *everything* had a comment and *most* comments added little or
nothing, it's more likely that the comments that are significant will
be overlooked.  Yes, one solution is to make all comments significant,
but it seems to me that just skipping over unwarranted comments makes
it more likely that the others will get noticed.

Cutting and pasting the tm.texi docs, complete, for each entry is
certainly an example of this.  There's a continuum of examplitude
between that and ideal comments.

> > #define FUNCTION_ARG_REGNO_P(r) m32c_function_arg_regno_p (r)
> 
> Even there:
> 
>    /* Return true if R is a hard register number in which arguments are
>       sometimes passed.  */

If I were to put a comment there at all, I'd put in something like this:

/* r1/r2 for A16, r0 for A24 */

IMHO your example is unwarranted because that much could be figured
out just by reading the macro's name *and* because it parrots
(paraphrasing) the documentation.

OTOH I also would have put that in the .c file, optimistically hoping
that someday it will become a target hook, and once you do that, the
comment becomes superfluous because the function says it's doing
exactly that.

> * Compared to the rest of developing a new port, the amount of effort 
> required for adding these comments is small.

Except that it happens at a time when you're methodically going
through the documentation adding a pile of empty functions and macros
just to get the port off the ground, and since you have the
documentation right there anyway and you're already bored out of your
skull with the mindless typing of empty functions, adding comments *at
that point* would probably drive me insane.

On the second pass, when I'm thinking about what each function should
do, I'm not even looking at the .h file any more, and why write a
comment that just repeats exactly what the code already says?  I mean,
we don't write comments in Spanish in case someone can't read English,
so why write them in English in case someone can't read C ?

[/me points out: this doesn't includes the cases where, I think we all
agree, comments are always warranted: when they *add* information that
isn't expressed in the C code, like why, caveats, gotchas,
obscurities, etc]

> * This is not a really big deal to me, so if it is a really big deal
> to you, I wouldn't want to spend a lot of time (for either of us) in
> trying to change your mind.

It's not normally a big deal for me, except that I too have a port
pending, and the only comment so far (since I addressed Joseph's
initial one) was about the sparsity of comments.  If a bit of mindless
commenting is what it takes to get a port approved, tell me when to
start typing.  But I'm not going to waste my time on it if all it's
going to do is make me wait another four weeks or more (sigh) because
I changed the patch and reset the approval clock.

So it's not a big deal to me to get my way, but it is a big deal to me
to find out what's going to maximize my chances of getting my port
approved.

> * If a reviewer chooses to require such documentation, it would be 
> better to provide it than argue about it; both alternatives will take 
> about the same amount of time, and I don't think a reviewer is obligated 
> to continue reviewing a patch if the submitter doesn't want to do what's 
> asked.

If the reviewer only says "everything needs comments" and isn't
specific, no, it's a lot more effort on the submitter's part.  Yes, if
the reviewer puts some thought into it and provides useful comments on
adding comments, the submitter is obliged to respond.

> For the case in question, Joseph is not a global write person, so his 
> comments are advisory.

BTW thanks to Joseph for taking the time to comment :-)

> Still, I think Aldy would be well-served to deal with the comments
> proactively, as some reviewers (me, for example) would probably
> require them.

Does that mean I should add comments to the pending m32c port?


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