From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 14323 invoked by alias); 30 Aug 2010 18:38:41 -0000 Received: (qmail 14309 invoked by uid 22791); 30 Aug 2010 18:38:40 -0000 X-SWARE-Spam-Status: No, hits=-6.1 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_HI,SPF_HELO_PASS,T_RP_MATCHES_RCVD X-Spam-Check-By: sourceware.org Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Mon, 30 Aug 2010 18:38:32 +0000 Received: from int-mx01.intmail.prod.int.phx2.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by mx1.redhat.com (8.13.8/8.13.8) with ESMTP id o7UIc8h0008263 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 30 Aug 2010 14:38:08 -0400 Received: from ns3.rdu.redhat.com (ns3.rdu.redhat.com [10.11.255.199]) by int-mx01.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id o7UIc8xL031416; Mon, 30 Aug 2010 14:38:08 -0400 Received: from opsy.redhat.com (ovpn01.gateway.prod.ext.phx2.redhat.com [10.5.9.1]) by ns3.rdu.redhat.com (8.13.8/8.13.8) with ESMTP id o7UIc78O011687; Mon, 30 Aug 2010 14:38:07 -0400 Received: by opsy.redhat.com (Postfix, from userid 500) id 028EF37822B; Mon, 30 Aug 2010 12:38:06 -0600 (MDT) From: Tom Tromey To: Jan Kratochvil Cc: Joel Brobecker , gdb-patches@sourceware.org Subject: Re: [patch] Code cleanup: Make function typedef for find memory region References: <20100830085953.GA25961@host1.dyn.jankratochvil.net> <20100830141454.GG2986@adacore.com> <20100830142507.GA1356@host1.dyn.jankratochvil.net> Date: Mon, 30 Aug 2010 18:38:00 -0000 In-Reply-To: <20100830142507.GA1356@host1.dyn.jankratochvil.net> (Jan Kratochvil's message of "Mon, 30 Aug 2010 16:25:07 +0200") Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2010-08/txt/msg00529.txt.bz2 >>>>> "Jan" == Jan Kratochvil writes: Jan> I am also for requiring comment to be placed at the function Jan> definition and not at its declaration. Using tag jumps one will Jan> never find the declaration and I have considered these functions to Jan> have no comment (randomly found now Jan> simple_displaced_step_copy_insn, it was a different function I had Jan> the problem with). I think there are three cases. One case is the "bcache" case: you have a relatively simple data structure with a defined public API. In this case, I find it it convenient to be able to read the header file to see the entire exported API, without being distracted by the implementation. This case is maybe not as typical as we might like; many data types in gdb are semi-opaque at best. The second case is implementations of virtual methods. Here, the comment belongs at the point of definition. I think commenting the method implementation is actually (mildly) bad, because it means copying documentation, with the problems that implies. The last case is the rest of gdb -- semi-opaque data structures, utility functions, etc. For these I think using the definition is preferable. That said, my general rule for hacking on gdb is to just follow whatever style is in use wherever I am hacking. If I were writing new code, I might aspire to the bcache approach; but otherwise I just comment the definition. Jan> I am also for forbidding putting comments there at both places as Jan> such way they get inconsistent soon or they differ etc. (randomly Jan> found init_type). I agree. Tom