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

[Jim Meyering]

On Sat, Sep 28, 2013 at 6:05 PM, Phillip Susi <address@hidden> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA512
>
> I see what you meant now about the comment style:
>
> *file1: add feature x
> *file2: same
> *file3: test feature x
> *file4: document feature x
>
> I don't think these kind of comments adds anything of value so I'd
> prefer to avoid it.  A few of the patches you posted also could use
> NEWS entries.

Hi Phillip,

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