On Tue, Sep 27, 2016 at 08:14:38PM -0400, Mark H Weaver wrote:
     
     Our conventions for commit logs, which follow the GNU Coding Standards
     for Change Logs (see section 6.8 of the GNU Coding Standards), is that
     explanations belong in the comments of the code itself, not in the
     commit log.  If that had been done in the example you give above, you
     would have known why the line was needed in a small fraction of the time
     that it must have taken you to perform all the steps above.

That can work in simple instances - where the change is a one liner or at least
where the change is confined to a few consecutive lines in one file.  But not
all changes are that simple.  Sometimes it is necessary to make a change which 
involves lots of small changes in lots of different places in lots of different
files.   In such cases it would be rediculous to append a comment to each line
changed.  In fact I have seen such code from the 1980s where almost every 4th line
has a comment like: 
  mode++; /* JMD 09/2/1981: Increment the mode count otherwise the crud wangler overflows 
                    in the case where grunger regurtitates */

The occasional such comment is ok, but when it's every third line it does nothing
for readability nor comprehensibility.
     
     However, I agree that commits that _remove_ code should include the
     rationale in the commit log, if the reason is not obvious and if there's
     no sensible place to put the explanation in the code.
     
     What do you think?

Well I certainly agree that adding a reason for a change is a good idea.  Even if
we do also have text in the message which is superfluous.

J'

Note to self:  Must write an improved version of gnulib's git-log-to-changelog script
which will satisfy the die-harders.


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