[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Phillip Susi
Subject: bug#15356: [PATCH 00/19] Fedora parted patches
Date: Sun, 29 Sep 2013 21:02:11 -0400
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:24.0) Gecko/20100101 Thunderbird/24.0

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

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


reply via email to

[Prev in Thread] Current Thread [Next in Thread]