Last time, I talked about how svn log (or similar) can be a key team communication tool. Let’s examine how individual commit messages play a role in that.

It’s time for a classic good-bad-ugly demonstration.

bad

worked some more on module x.

Cool. So apparently we already knew you were working on module x. Is there some method holding you back? Did you finish it? Which files are you working in?

Checking in WidgetFactoryEnablerUtility.java.

What does it do? What code will it affect? Does it belong to a module of some sort?

good

Continued work on Module X in DatabaseConnector.java. Having difficulty properly escaping input, so interaction with Module Y will work with correct input, but not input requiring escaping.
Finished: open() and disconnect() methods.
TODO: Error checking and input escaping.
Known bugs: inputting “; DROP TABLE ;” for name drops the table.

Specific about the file, how changes affect interactions with other areas of the project, and specific about the effects of known bugs.

aside: Should you commit with bugs?

Do the bugs break the build? If so, don’t commit.
Will committing the bugs confuse someone? If so, don’t commit.
Does everyone know the bug exists and how it affects their code? Committing the bug with documentation in the commit message is probably a better choice than waiting until it’s fixed (or forgetting it’s not fixed).

Added WidgetFactoryEnablerUtility.java for use in the WidgetFactory module. Provides enabler methods for non-standard Java implementations.

Specific about which file, what was done with it, what it’s associated with, and what it does.

Added several .png files to the images folder – new icons for the toolbar.

There’s little to no benefit of saying exactly which .pngs were added, but definitely give a purpose.

ugly

IT’S WORRRKINGNGGGGGGGGGGGG!!!!

or

fixed it

I probably did the former a dozen times this year. Sometimes you get caught in the moment. Be excited, do some high fives, but be a bit more descriptive about what “it” is and why it wasn’t considered working before so we know what working means now.

[comments about 60 files that have changed]

You might want to commit more often.

Deleting file SomeClass.m – don’t know why it’s there.

It might be time for a code review.

Adding GiganticBinaryFile.mp4 – used in testing.

This will likely be an unpleasant surprise on everyone’s next update. It may be better to include in the test script a command to fetch the file from an HTTP server if it doesn’t already exist in the test folders.