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
> 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.

> 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.