Subject: Re: bug#15356: [PATCH 00/19] Fedora parted patches

From: Phillip Susi <[email-masked]>
Date: Sun, 29 Sep 2013 21:02:11 -0400

I find that most comments that get added this way end up being of the
useless restating the obvious variety.  In the event that some code
isn't obvious from the general description, either the description
needs a little more fleshing out, or the code in question deserves a
good comment in the code instead of a one liner in the commit message.

On 09/29/2013 11:59 AM, Jim Meyering wrote:
> I have found that the discipline imposed by having to write up
> that style of ChangeLog entry tends to help me spot my own errors
> (as I write it), and also makes it easier to review changes written
> by others -- when they adopt that style.  Of course, it works only
> if you provide the sort of detail that is useful.  If you merely
> say "as above", referring to the high-level what-this-does
> description, it provides almost no value.  However, the intent is
> to provide additional, typically lower-level detail.  Sometimes, it
> feels stilted, because you've already given that detail in the
> top-level description, but when the implementation details are not
> 100% obvious, and especially when you're changing types, adding or
> removing global variables, parameters, etc. there are plenty of
> ways to make a commit message better by saying more. Given a
> well-written ChangeLog, it is often possible to use it as a spec
> and produce an identical patch. This ostensible duplication is what
> makes it so useful (and hard to write if you're not used to it) for
> catching differences between the detailed, expressed intent of the
> patch-writer, and the actual patch.
> 
> Sure, it is an added cost, but in the write-once-read-many coding 
> world, it is a worthwhile investment.  Your patches will be read
> by far more than one or two people, so optimizing for the reader
> makes sense.
> 
> Jim
> 
> 
>