A recent committer writes:
* modeline.el (make-modeline-command-wrapper):
Be more reasonable about the implementation of this wrapper, don't
require that the value of COMMAND be available at macro-expansion
time. (Basically, implement a closure.)
* modeline.el (add-minor-mode):
Remove a workaround and misguided comment that are no longer
necessary or exact.
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
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 ...",
..." 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