Rant about ChangeLog entries and commit messages

[Nicholas Nethercote]

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.)  That 
comment is not a blemish but an invaluable record of an unusual case that 
someone didn't anticipate.  If the bug-fix was pre-empted by a lengthy email 
exchange, include some or all of that exchange if it helps.

Nick