This is part of a series on good commits.

Imagine that you had a narrative view of your project’s history, telling the story of its evolution and the intent behind each change. Imagine that our project had a Twitter timeline.

Now stop imagining, and start making better commit messages.

This is what many project histories look like:

Author    Date         Message
---       ---          ---    
druttka   6/13 10:58        
jrob      6/13 10:52   did stuff. ps why don't ruttka add messages? 
druttka   6/13 09:15        
jrob      6/13 08:45   things are done.
druttka   6/13 07:32

What if it looked like this instead?!

Author    Date         Message    
---       ---          ---    
druttka   6/13 10:58   Fix serialization of foo  
jrob      6/13 10:52   Add support for bar
druttka   6/13 09:15   Support baz
jrob      6/13 08:45   Add Foo to IBarProvider
druttka   6/13 07:32   Reduce Wizzbang execution time

What if you could then see additional detail for the serialization fix? By looking at the expanded log statement, you might see more detailed information like

Fix serialization of foo

Needed to zingify the wizzbangs

Amazing!!

The applications for more explanitory messages are endless. Some examples include

  • Code review. Get an idea of what the author intended before you see what they implemented.
  • Diff debugging. Get an idea of what changed when, and why.
  • Reviewing old fixes. A similar issue appears later, and you can go find when it was fixed before to see how.
  • Communication. Maybe your team doesn’t have a regular communication loop, and viewing the history is how you can stay up to date on changes you weren’t directly involved in.

Common Excuses (and Counters)⌗

I usually hear three reasons for missing or poor commit messages. Let’s see what they are and try to remove the barriers.

  1. A person claims they don’t know what to say. Just say what you did. Start with a brief synopsis on the first line. Be imperative, and include an issue number if appropriate. Something like “Implement new logging mechanism”. If there’s more context to be given about why or how this change was made, that can be provided on following lines.
  2. A person just isn’t in the habit. Enforce it. TFS has check-in policies. Git opens a text editor for you if you don’t provide a message with -m, and aborts the commit if you leave the message empty.
  3. A person claims that it’s a waste of time. That’s quite relative. Compare that with the time you already spent investigating, planning, implementing, and (hopefully) testing the change itself. Also consider the time you’ll save diffing revisions later, when you could just grep the log.

Note: Will recently did a post on good commits, too. Read it.