From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 5563 invoked by alias); 3 Dec 2007 09:28:51 -0000 Received: (qmail 5551 invoked by uid 22791); 3 Dec 2007 09:28:50 -0000 X-Spam-Check-By: sourceware.org Received: from mx1.suse.de (HELO mx1.suse.de) (195.135.220.2) by sourceware.org (qpsmtpd/0.31) with ESMTP; Mon, 03 Dec 2007 09:28:44 +0000 Received: from Relay1.suse.de (mail2.suse.de [195.135.221.8]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.suse.de (Postfix) with ESMTP id 9A8FC210A6; Mon, 3 Dec 2007 10:28:41 +0100 (CET) From: Andreas Schwab To: Nicholas Nethercote Cc: Samuel Tardieu , gcc@gcc.gnu.org Subject: Re: Rant about ChangeLog entries and commit messages References: <2007-12-02-11-05-39+trackit+sam@rfc1149.net> X-Yow: Now I need a suntan, a tennis lesson, Annette Funicello and two dozen Day-Glo orange paper jumpsuits!! Date: Mon, 03 Dec 2007 09:28:00 -0000 In-Reply-To: (Nicholas Nethercote's message of "Mon\, 3 Dec 2007 17\:40\:47 +1100 \(EST\)") Message-ID: User-Agent: Gnus/5.110006 (No Gnus v0.6) Emacs/22.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: 8bit X-IsSubscribed: yes 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/msg00060.txt.bz2 Nicholas Nethercote writes: > 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.) 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."