From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 6618 invoked by alias); 25 Sep 2003 19:41:31 -0000 Mailing-List: contact gdb-patches-help@sources.redhat.com; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sources.redhat.com Received: (qmail 6611 invoked from network); 25 Sep 2003 19:41:30 -0000 Received: from unknown (HELO localhost.redhat.com) (207.219.125.105) by sources.redhat.com with SMTP; 25 Sep 2003 19:41:30 -0000 Received: from redhat.com (localhost [127.0.0.1]) by localhost.redhat.com (Postfix) with ESMTP id 4EAC22B89; Thu, 25 Sep 2003 15:41:35 -0400 (EDT) Message-ID: <3F7344EF.30407@redhat.com> Date: Thu, 25 Sep 2003 19:41:00 -0000 From: Andrew Cagney User-Agent: Mozilla/5.0 (X11; U; NetBSD macppc; en-US; rv:1.0.2) Gecko/20030820 X-Accept-Language: en-us, en MIME-Version: 1.0 To: Jim Ingham Cc: gdb-patches@sources.redhat.com Subject: Re: complete command doesn't work for files... References: <20030924232504.GL1020@gnat.com> <3F7228FE.7040908@redhat.com> <1A6E465C-EF8B-11D7-BEC8-00039379E320@apple.com> Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit X-SW-Source: 2003-09/txt/msg00571.txt.bz2 > Comments in code should not say why what is no longer in the code was incorrect... That is just confusing. So the text of the ChangeLog is not appropriate as a comment in the code. From the change log doco: > There's no need to describe the full purpose of the changes or how they work together. If you think that a change calls for explanation, you're probably right. Please do explain it--but please put the explanation in comments in the code, where people will see it whenever they see the code. For example, "New function" is enough for the change log when you add a function, because there should be a comment before the function definition to explain what it does. The commentary should alert the user as to issues with the relevant code, explaining, where applicable, why apparently simpler alternative techniques don't work. Andrew