I want to confiscate every dev's * key because while converting the
Wesnoth repo I've just fixed about the hundredth comment that does this:
------------------------------------------------------------------------------
Fossil-ID: 29314
* Document weapon/second_weapon addition and changes on RC imagepath
* function
------------------------------------------------------------------------------
The obvious thing that is wrong with this is the second '*'; the bare
word 'function' is not a list entry.
The unobvious thing that is wrong with this is the *first* '*'. This
entire comment should not have been written as a bullet item. Because
there aren't any other items in it! There's no list here!
A change comment like this is OK:
------------------------------------------------------------------------------
A summary of what I did to fix a random bug
* This is the first thing
* This is the second
------------------------------------------------------------------------------
A change comment like this is not OK:
------------------------------------------------------------------------------
* This is a random thing I did.
------------------------------------------------------------------------------
That leading '* ' is just a hindrance to readability, a visual bump in
the road. When your comment history is over 50K commits long this sort
of small additional friction matters.
The following is also *not* OK:
------------------------------------------------------------------------------
* This is one random thing I did.
* This is another random thing I did.
* This is a third random thing I did.
------------------------------------------------------------------------------
Why is this not OK?
Well, the obvious reason is that there is no summary line tying all
the items together. This matters more in git-land because so many of
the tools just show first summary lines.
The less-obvious reason is that if you write a comment like this, your
single commit is almost certainly doing too much. You should break it
up into several commits, each with one topic that becomes a single
(non-bullet) item in its own change comment.
The next time you are tempted to press your '*' key when writing a
change comment, stop and think. Is it just going to be noise? If
so, stop and slap your own hand.
More generally, give a little thought to what the shape of your
comment says about the shape of your commit. Is it trying to describe
too many different and unrelated changes in one go? Does it have a
proper first summary line that will minimize the overhead of reading
it for someone six months down the road?
There's a programmer's proverb: "Always code as if the guy who ends up
maintaining your code will be a violent psychopath who knows where you
live. Code for readability."
That applies to comments, too. At the scale of this project, such
details really matter.
--
<a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>
Idealism is the noble toga that political gentlemen drape over their
will to power. -- Aldous Huxley
_______________________________________________
Wesnoth-dev mailing list
[email protected]
https://mail.gna.org/listinfo/wesnoth-dev
