From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: git history tracking across renames (and emacs support) (Was: The name gnus-cloud.el) Date: Mon, 08 Jan 2018 20:30:46 +0200 Message-ID: <83zi5o6w4p.fsf@gnu.org> References: <87bmj6dda0.fsf@linux-m68k.org> <87vahe911g.fsf@lifelogs.com> <87374id7jy.fsf@linux-m68k.org> <877ett8g7k.fsf@lifelogs.com> <87a7yn7tqp.fsf@lifelogs.com> <878te75xa1.fsf@lifelogs.com> <87ind6l2tt.fsf@lifelogs.com> <877etklvsa.fsf@lifelogs.com> <83y3m0pv8u.fsf@gnu.org> <86608msw0h.fsf@dod.no> <838tdiet25.fsf@gnu.org> <87y3li4vh7.fsf@telefonica.net> <87efnan46u.fsf@linux-m68k.org> <86wp12qtgo.fsf@dod.no> <83tvw6chqv.fsf@gnu.org> <86shbprix7.fsf_-_@dod.no> <7c7503b4-1f82-8a25-fedd-c61c3e7629f6@cs.ucla.edu> Reply-To: Eli Zaretskii NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1515436199 5412 195.159.176.226 (8 Jan 2018 18:29:59 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 8 Jan 2018 18:29:59 +0000 (UTC) Cc: sb@dod.no, rms@gnu.org, emacs-devel@gnu.org To: Paul Eggert Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Jan 08 19:29:54 2018 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eYcBB-0000iK-Pw for ged-emacs-devel@m.gmane.org; Mon, 08 Jan 2018 19:29:49 +0100 Original-Received: from localhost ([::1]:50325 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eYcD9-0004Zg-CF for ged-emacs-devel@m.gmane.org; Mon, 08 Jan 2018 13:31:51 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:34834) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eYcCS-0004ZU-12 for emacs-devel@gnu.org; Mon, 08 Jan 2018 13:31:09 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eYcCO-0006Dg-TX for emacs-devel@gnu.org; Mon, 08 Jan 2018 13:31:08 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:39535) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eYcCO-0006Da-QU; Mon, 08 Jan 2018 13:31:04 -0500 Original-Received: from [176.228.60.248] (port=3451 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1eYcCH-0007IS-Mm; Mon, 08 Jan 2018 13:30:58 -0500 In-reply-to: <7c7503b4-1f82-8a25-fedd-c61c3e7629f6@cs.ucla.edu> (message from Paul Eggert on Sun, 7 Jan 2018 20:22:28 -0800) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:221714 Archived-At: > From: Paul Eggert > Date: Sun, 7 Jan 2018 20:22:28 -0800 > Cc: sb@dod.no, emacs-devel@gnu.org > > > Our current practice is to put the explanation into comments in the > > code. > > Although that may be what the guidelines say, it's not done that often and it's > often not worth doing. This is because code comments should explain the code, > and not waste time explaining the code's history -- unless knowing the history > is helpful for understanding the code's current state, which it's often not. > > For example, I'm attaching a small Emacs patch I installed last month. If the > guidelines really required us to put change descriptions into code commentary, > the patch should have changed the declaration in src/sysdep.c to look something > like this: > > /* This variable used to be extern, but is static now. */ > static pthread_t main_thread_id; > > But such a comment would have been silly, as it would record a fact that is > irrelevant to how Emacs works today, and this historical footnote would take up > valuable real estate on the screens of today's maintainers for no good reason. Actually, that's not the reason why this comment would be silly. It would be silly because there's no need to explain why a certain variable is static. Also, when/if someone looks at the diffs, they will see exactly what the comment says, so the comment doesn't add any useful information. If you somehow understood what Richard said to mean we need to add useless comments, then I'm sure we could clarify that comments should add useful information. (I thought it was obvious, but that's me.)