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