Category Archives: DS

Agile, DS, Scrum

writing good commit messages

1 Comment

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.

Agile, DS, Scrum, XP

total source control

1 Comment

In any software engineering project, there is code. These days, most software engineering projects also involve many people. Sometimes, in spite of efforts towards orthogonality, more than one of these people must work on code in the same source file. This is a merge conflict.

Aside that, there is the simple matter of synchronizing the existence of code that one person creates that another does not have. Simpler to solve, but equally important to progress as the merge conflict.

Sometimes, we do not give sufficient information to the source control system to unambiguously resolve a merge. In Subversion, this is the conflicted state.

What do we do about the conflicted state?

We take steps to avert a conflicted state:

  • Commit early; commit often.
  • Try to work on different parts of the code. Different modules, different files, or even just different methods.
  • Mock objects. This is one of the least-utilized but most powerful conflict-avoidance practices.

In spite of this, almost every team eventually experiences a merge conflict. Methods for dealing with this vary:

  • Destroy one person’s code, usually the one with less lines.
  • Hand-pick lines to include from the merge and mark resolve (this is remarkably rare)
  • Revert.

Usually, merges conflicts are surprising because of when they happen. Usually, it is a late night or early morning where the last committer is nowhere in sight.

To keep that person from being helpless, source control systems allow a comment to be attached to each commit of files.

Opportunity Abound

By making your commit messages useful, you can do more than save that hapless conflicted soul. By writing good messages, you enhance intrateam communication. ALERT: SPOILERS AHEAD. The one command you need to be an effective coach or team member is… 

svn log

Use it during standups to remember just what exactly it was that you did last team time four days ago. Understand why 17 lines of code are gone from a file. Understand that Page X’s improper rendering is a known bug.

Bonus

The real bonus of having a quality source control log is that you have a concrete answer to the invariable coach question, “How is everything going?” They might (hint hint hint hint) even get involved enough to read the logs themselves, perhaps (hint hint hint hint) using a tool such as trac.

I honestly believe that on a day-to-day basis, barring new client information, a tool like trac coupled with excellently-written log messages can eliminate the need for a verbal standup for the team and for the coach. That, of course, depends on the definition of “excellently-written” log messages, which I’ll cover in my next entry. In the mean time, feel free to tell me why I’m wrong. 🙂