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

[Phillip Susi]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

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

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBCgAGBQJSSM2TAAoJEJrBOlT6nu75r7sH/2930x5RmfPx1kAd5//NK7Hk
TbeDEaE6O9uBTWrGmVmN9ysw9/cfwRgOz3HbZnjt+zRLkS4NsS8vZi+IUb7fvPRd
Uh6KAO+v4XWW8A3Uau/kKL57hd1qo/BsRp813r9fAO219o5hxFpSpw3ITowKgNEH
th+xGo7dK5PxULQigmfKn48LuRBu5+ATjPYg2q3R1/3qSAqE8DeAmxjhgjqlJbuB
YkYgNrX264O5DH9iaOrxVBacfDuG8O/m0IHXKzWpSuFT4guEr/7WVhI8VLOyKJwq
Vvk1I6yPABSdLA234En9mzI4G6XF8/KRrRnp3fYr6sDPotKXumeU8YzjyxPDhUc=
=d/w2
-----END PGP SIGNATURE-----