Re: How much explanation to include in change descriptions

[John Darrington]

On Tue, Jan 16, 2018 at 08:11:11PM -0500, Richard Stallman wrote:
     
       >  >    > Fix .gdbinit to work with Lisp_Word (Bug#29957)
       >  >
       >  > is unhelpfully terse: it makes people work harder to understand the 
change.

I firmly believe that if something is needed to help people understand how the 
code works, then either the code needs rewriting or it needs a comment (or
both). 
     
       > We could change the line to:
     
       > Fix .gdbinit when Lisp_Word is pointer (Bug#29957)
     
       > as this captures the detail that was missing in the too-terse version.
     
     I agree that would be better.  But 
     
       > Cast Lisp_Word value to EMACS_INT, since it might be a pointer 
(Bug#29957)
     
     seems even better.
     
I agree that this version is better than the others previously suggested, and it
emphasises a point I have raised on several occasions, but unfortunately many
still don't seem to grasp:   

 The purpose of the change log is to explain *why* a change was made, not to 
explain how the code works.    Obviously this tenet must be applied with 
common sense - for reference and orientation it is also useful to give a brief
summary of the change.  Similarly, if the reason is blindingly obvious (for
example, the change corrects a typo which prevented compilation) then it is
acceptable to omit the reason.
     

J'

-- 
Avoid eavesdropping.  Send strong encrypted email.
PGP Public key ID: 1024D/2DE827B3 
fingerprint = 8797 A26D 0854 2EAB 0285  A290 8A67 719C 2DE8 27B3
See http://sks-keyservers.net or any PGP keyserver for public key.

signature.asc
Description: Digital signature