On Sat, Sep 28, 2013 at 6:05 PM, Phillip Susi <ps...@ubuntu.com> 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
