A comment on style in commit/change log messages

A recent committer writes: Mercurial, like other DVCSes, provides several ways to get one-line summaries of changes. It's very helpful in that context if the first line is active and descriptive. In this case, I suggest Make #'make-modeline-command-wrapper evaluate COMMAND lazily. for the first line, followed by This allows the wrapper to called when the value of COMMAND becomes available only after macro-expansion time. Implemented by what is basically a closure. N.B. Some style guides suggest avoiding description of the implementation in such messages, but I find this kind of comment useful, as it helps me identify changes that are worth studying for their own sake (vs reviewing for correctness). If it's not easy to come up with such a terse statement (and I admit I had to think for a couple minutes, and that wasn't my first try), I would prefer reading simply Improve make-modeline-command-wrapper. over the vague "be more reasonable about the implementation". YMMV, but I find that I personally waste time trying to figure out what's "reasonable", or reading further in the log to find out when I really don't have any business doing so. The more terse form I find easier to accept with "that's nice" and move on. It emphasizes the important information about what was improved, too. The log for "add-minor-mode" is precise. It would be nice if it were shortened to fit on one line, such as Remove an unnecessary workaround, and a misguided comment. (This isn't very helpful in this case because it's a minor change piggybacked on a more important one in the same commit, and so won't be shown in a line-per-commit format. However, if it were a standalone commit the shorter message looks much nicer IMO.) I recognize that not all good coders or even people who otherwise write well will find it easy to come up with such terse first lines. If it's not a profitable use of your time, I recommend developing a small repertoire of phrases which may be imprecise but don't add random vagueness such as "improve ...", "fix bug in ...", "document ..." etc followed by the name of the function or whatever. Note that I specifically mentioned what *I* would like to read. I'm only one contributor in this context, and may or may not be representative of others. Comments about what would make log message more useful to *you* are welcome! _______________________________________________ XEmacs-Beta mailing list XEmacs-Beta(a)xemacs.org http://lists.xemacs.org/mailman/listinfo/xemacs-beta