-----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-----
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
Open Source Applications Foundation "Dev" mailing list
http://lists.osafoundation.org/mailman/listinfo/dev
