On Mon, May 17, 2010 at 6:25 PM, sebb <[email protected]> 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: [email protected] For additional commands, e-mail: [email protected]
