Heavy on the Geekery

When developing software, any time you change a bit o’ source code you can type a paragraph or two describing the changes. This text is called a “commit message.” Sandy at work said my commit messages were good. Here’s my advice for writing a good commit message.

There are two reasons people will read your commit message. One, you just checked in some code and everyone got an email of the changes. Or two, someone down the road is tracking down a bug and they want to know what your change does.

Stuff to keep in mind:

• Be concise. People don’t read long shit
• Summarize the reason for the changes. Don’t describe every change line-by-line
• If you’re fixing a bug then give a numbered list of steps that can be used to reproduce the bug
• Don’t explain the architecture of the code. This is better done via code comments or a wiki
• Reference any related bug numbers or patches
• A little humor is ok, it keeps people interested. Talk about laser beams if you have to.
• Don’t reference things that aren’t permanent, like emails or conversations. The following are really, really bad, “the change we talked about in the hall” or “Jim suggested this change in an email last week.“