56 lines
3.5 KiB
Plaintext
56 lines
3.5 KiB
Plaintext
Why I want to confiscate every programmer’s * key
|
|
<p>I just sent mail to the Battle for Wesnoth developer list titled “Why I want to confiscate every dev’s * key”. The points in it probably deserve a wider audience.</p>
|
|
<p><span id="more-4824"></span></p>
|
|
<p>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:</p>
|
|
<pre language="C">
|
|
------------------------------------------------------------------------------
|
|
Fossil-ID: 29314
|
|
|
|
* Document weapon/second_weapon addition and changes on RC imagepath
|
|
* function
|
|
|
|
------------------------------------------------------------------------------
|
|
</pre>
|
|
<p>The obvious thing that is wrong with this is the second ‘*'; the bare word ‘function’ is not a list entry.</p>
|
|
<p>The unobvious thing that is wrong with this is the <em>first</em> ‘*’. 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!</p>
|
|
<p>A change comment like this is OK:</p>
|
|
<pre language="C">
|
|
------------------------------------------------------------------------------
|
|
|
|
A summary of what I did to fix a random bug
|
|
|
|
* This is the first thing
|
|
|
|
* This is the second
|
|
|
|
------------------------------------------------------------------------------
|
|
</pre>
|
|
<p>A change comment like this is not OK:</p>
|
|
<pre language="C">
|
|
------------------------------------------------------------------------------
|
|
|
|
* This is a random thing I did.
|
|
|
|
------------------------------------------------------------------------------
|
|
</pre>
|
|
<p>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.</p>
|
|
<p>The following is also *not* OK:</p>
|
|
<pre language="C">
|
|
------------------------------------------------------------------------------
|
|
|
|
* This is one random thing I did.
|
|
|
|
* This is another random thing I did.
|
|
|
|
* This is a third random thing I did.
|
|
|
|
------------------------------------------------------------------------------
|
|
</pre>
|
|
<p>Why is this not OK? </p>
|
|
<p>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. </p>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
<p>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?</p>
|
|
<p>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.”</p>
|
|
<p>That applies to comments, too. At the scale of this project [8 years, over 55K commits], such details really matter.</p>
|