This is the mail archive of the gcc@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: Rant about ChangeLog entries and commit messages


Nicholas Nethercote <njn@csse.unimelb.edu.au> writes:

> On Sun, 2 Dec 2007, Andreas Schwab wrote:
>
>>> | 2007-11-30  Jan Hubicka  <jh@suse.cz>
>>> |
>>> |         * ggc-common.c (dump_ggc_loc_statistics): Reset ggc_force_collect
>>> |         flag.
>>>
>>> How could a newcomer guess why the gcc_force_collect flag needs to be
>>> reset?
>>
>> That is supposed to be written in a comment.
>
> Indeed.  Some advice I once wrote:  Often I see a commit with a log
> message that lovingly explains a small change made to fix a subtle
> problem, but adds no comments to the code.  Don't do this! Put that
> careful description in a comment, where people can actually see it.
> (Commit logs are basically invisible; even if they are auto-emailed to all
> developers, they are soon forgotten, and they don't benefit people not on
> the email list.)

Moreover, if you later look at a commit log you don't know whether it
still describes the current code, you have to carefully inspect the
later history whether there were any further refinements, for example.
A comment will be updated over time and is always (supposed to be) on
par with the code.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
PGP key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."


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