From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 20979 invoked by alias); 3 Dec 2007 06:45:41 -0000 Received: (qmail 20969 invoked by uid 22791); 3 Dec 2007 06:45:41 -0000 X-Spam-Check-By: sourceware.org Received: from mulga.csse.unimelb.edu.au (HELO mulga.csse.unimelb.edu.au) (128.250.1.22) by sourceware.org (qpsmtpd/0.31) with ESMTP; Mon, 03 Dec 2007 06:45:37 +0000 Received: from localhost (localhost [127.0.0.1]) by mulga.csse.unimelb.edu.au with ESMTP id lB36jSYm016045; Mon, 3 Dec 2007 17:45:29 +1100 (EST) Received: from mulga.csse.unimelb.edu.au ([127.0.0.1]) by localhost (mulga.csse.unimelb.edu.au [127.0.0.1]) (amavisd-new, port 10024) with LMTP id 14784-02-9; Mon, 3 Dec 2007 17:45:27 +1100 (EST) Received: from mulga.csse.unimelb.edu.au (localhost [127.0.0.1]) by mulga.csse.unimelb.edu.au with ESMTP id lB36enAd008193; Mon, 3 Dec 2007 17:40:49 +1100 (EST) Received: from localhost (njn@localhost) by mulga.csse.unimelb.edu.au (8.13.8+Sun/8.13.8/Submit) with ESMTP id lB36el0x008170; Mon, 3 Dec 2007 17:40:48 +1100 (EST) Date: Mon, 03 Dec 2007 06:45:00 -0000 From: Nicholas Nethercote To: Andreas Schwab cc: Samuel Tardieu , gcc@gcc.gnu.org Subject: Re: Rant about ChangeLog entries and commit messages In-Reply-To: Message-ID: References: <2007-12-02-11-05-39+trackit+sam@rfc1149.net> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed Mailing-List: contact gcc-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Archive: List-Post: List-Help: Sender: gcc-owner@gcc.gnu.org X-SW-Source: 2007-12/txt/msg00059.txt.bz2 On Sun, 2 Dec 2007, Andreas Schwab wrote: >> | 2007-11-30 Jan Hubicka >> | >> | * 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