[Dev] Another point of view on checkin comments

[Ted Leung]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

+1.

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  
> you
> as an author for a piece of text (email to dev, bug report, FAQ,  
> commit
> message) to spend the extra time making sure you write good and  
> complete
> 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  
> more
> usable, this number will go up. There are also people who find the
> commits via Bonsai, ViewCVS, WebSVN or other tools, or by simply  
> reading
> 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  
> could
> 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  
> the
> number.
>
> 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  
> change
> 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  
> find
> 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
> http://lists.osafoundation.org/mailman/listinfo/dev


-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (Darwin)

iD8DBQFDZ9WRvrorh/X8S0IRAkVDAKD2mvg8wunzEi/PZjVL1EVQlOuMTgCggU3v
Z93my2sGet1cA75paAmfVxs=
=AZJV
-----END PGP SIGNATURE-----