[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: Paul Eggert
Subject: Re: git history tracking across renames (and emacs support) (Was: The name gnus-cloud.el)
Date: Sun, 7 Jan 2018 20:22:28 -0800
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.5.0

Richard Stallman wrote:

   > What would be most helpful (and I realize I'm asking for a lot) would be
   > ChangeLog entries or commit messages (it doesn't matter which) that 
explain the
   > *motivation* for each change.

Our current practice is to put the explanation into comments in the

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.

But if there is no natural place for the explanation in the source
code, you should put it in the history.

That's too weak, as the example comment above should not be added to the code even though it is in the natural place for the explanation.

For changes to code, 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 full explanation in comments in the code,

This is too strong. That last sentence should begin like this instead:

"Please do explain it---but please put the full explanation of the new code in comments in the code,"

where people will see it whenever they see the code.  For example,

and here, after "see the code", insert:

", and please limit the ChangeLog entry to non-obvious change-related aspects that do not appear in the new code's comments"

``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, how to call it, and so on.

Attachment: 0001-Make-main_thread_id-private.patch
Description: Text Data

reply via email to

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