[Dev] Another point of view on checkin comments
twl at osafoundation.org
Tue Nov 1 12:52:22 PST 2005
-----BEGIN PGP SIGNED MESSAGE-----
In open source projects we should optimize for readers.
On Nov 1, 2005, at 11:59 AM, Heikki Toivonen wrote:
> The book "Producing Open Source Software" makes a good argument for
> as an author for a piece of text (email to dev, bug report, FAQ,
> message) to spend the extra time making sure you write good and
> documentation. The argument is that there is only one person (you)
> writing the piece of documentation, but many many more people reading
> that piece. So if you have to spend a minute, or ten minutes more of
> your time to gather all the pointers and summarize properly, it will
> save much more time from the collective readership.
> Right now our commits list has 35 subscribers. As Chandler becomes
> usable, this number will go up. There are also people who find the
> commits via Bonsai, ViewCVS, WebSVN or other tools, or by simply
> the code and svn history.
> So as an example, if there is a checkin comment like this:
> Fixed bug XXXX.
> It means that every person that sees that checkin comment will have to
> somehow find their way to the bug to see what this checkin fixes. In
> some cases their tool of choice makes this an automatic link so it
> be just one click of the mouse. In some other cases they will have to
> select it with the mouse, copy it into the clipboard, switch to a
> browser window, then depending on whether XXXX was a link or a bug
> number paste it to URLbar or navigate to a Bugzilla page, and paste
> Some code changes are obvious in the way they address a problem, but
> that is not the case for all changes. If that is not addressed in the
> bug either, the readers of the code will be at a loss. Speaking from
> personal experience, a year from now I will probably not remember
> why I
> did some code change without a good comment myself.
> If the committer made a mistake with the bug number, then readers will
> have a really hard time figuring out what is going on.
> Compare that to an imaginary checkin that says:
> Fixed bug XXXX, sidebar does not take focus, r=alecf.
> Need to explicitly set the focus on an individual entry by calling
> wx.SetFocus() of the underlying widget on mouse click, because this
> does not happen automatically yet.
> Now, the commits list subject line already shows what the fix is for
> (and who reviewed it). Additionally, the comment explains why the
> fixes the issue. There may be no need for the reader to even go visit
> the bug - everything is contained in the commit message (this is not
> always possible, i.e. a change addresses a complex issue).
> Even if there was a typo with the bug number, the reader can easily
> the bug based on the description of the fix.
> And someone reading the code later will understand why those lines of
> code are there.
> Heikki Toivonen
> _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
> Open Source Applications Foundation "Dev" mailing list
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (Darwin)
-----END PGP SIGNATURE-----
More information about the Dev