[ALL] Commit log messages (was: [scxml-eclipse] Commit messages)

[sebb <se...@gmail.com>]

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

Re: [ALL] Commit log messages (was: [scxml-eclipse] Commit messages)

[Rahul Akolkar <ra...@gmail.com>]

On Mon, May 17, 2010 at 6:25 PM, sebb <se...@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