On 12/2/07, Bernd Schmidt <[EMAIL PROTECTED]> wrote: > Richard Kenner wrote: > >>> How could a newcomer guess why the gcc_force_collect flag needs to be > >>> reset? > >> That is supposed to be written in a comment. The change log entry > >> should describe _what_ is being changed, so that you can find out when a > >> particular change was made. > > > > Not quite. The comments are supposed to say why the code is doing what > > it's doing (and, where it's helpful, why it ISN'T doing something else). > > Purely historical references in the comments that don't serve to clarify > > the present code are discouraged. (We don't want comments turning in a > > blog, for example.) > > > > I view the description in the gcc-patches message as PART of the CM history > > of GCC in that IT'S the place to go to get this information. What's > > unfortunate, I think, is that there's no easy way to find this message from > > the CM revision number. > > I think that's Samuel's point - it would be much better to have them in > the commit log. FWIW, I agree completely - I've never found ChangeLogs > useful, I hate writing them, and I think the linux-kernel guys these > days generally have much better checkin messages than we do. >
+1. I have never, in 7 years of working on and debugging gcc, found the ChangeLog to be useful in debugging a problem. They are like a useless version of svn diff output. If I wanted to know what the change did, i'd look at what the change did. The ChangeLog is well nigh useless even for that compared to the actual diff. I'd go even further, and say if the GNU coding standards say we shouldn't be putting descriptions of why we are changing things in the ChangeLog, than they should be changed and should be ignored on this point until they do. Pointing to them as the if they are The One True Way seems very suspect to me. After all, how else would they ever improve if nobody tries anything different? --Dan
