commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rahul Akolkar <>
Subject Re: [ALL] Commit log messages (was: [scxml-eclipse] Commit messages)
Date Tue, 18 May 2010 01:58:55 GMT
On Mon, May 17, 2010 at 6:25 PM, sebb <> wrote:
> 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.

Indeed, the former isn't meant to take the place of the latter.

For a commit (especially larger ones), I see the commit message as an
abstract of the work done.


> [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:
For additional commands, e-mail:

View raw message