commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rahul Akolkar <rahul.akol...@gmail.com>
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 <sebbaz@gmail.com> 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.
>
<snip/>

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.

-Rahul


> [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