This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
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."