commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <seb...@gmail.com>
Subject [ALL] Commit log messages (was: [scxml-eclipse] Commit messages)
Date Mon, 17 May 2010 22:25:16 GMT
I largely agree with what was said about commit messages, but I
think it's important to ensure that code comments aren't thereby
neglected.

[BTW, I'm not implying anything about the scxml code - this is a general point]

AIUI commit log messages are not versioned so if they are changed,
that's it - the previous log message is no more, and is not recoverable
(except by trawling mailing lists).

I see commit log messages primarily as providing useful information for the
reviewer of the changes (and hopefully later via the history, but that is
not guaranteed).

If there is any tricky code, or particular design decisions made, then
I think these should also be present as comments in the code or
perhaps the package.html files.

Recently I needed to trace the reason for some odd looking code in a
(non-Commons) project and it took a couple of hours to find. This was
partly because the commit history had not been preserved, but even
without that difficulty, it would still have taken much longer than
necessary.

So please: if the code won't be easy to understand in the future
without information from the commit log message, then the information
should also be added as code comments.

Thanks.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message