[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: git history tracking across renames (and emacs support) (Was: The na

From: Eli Zaretskii
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

> From: Paul Eggert <address@hidden>
> Date: Sun, 7 Jan 2018 20:22:28 -0800
> Cc: address@hidden, address@hidden
> > 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.)

reply via email to

[Prev in Thread] Current Thread [Next in Thread]