Lightning Talk: Do Your Commit Messages Suck

by Ryan McGeary

Introduction

In the lightning talk 'Do Your Commit Messages Suck' presented by Ryan McGeary at the Rocky Mountain Ruby 2011, the focus is on the importance of clear and effective commit messages in collaborative software projects. Communication is key in software development, and well-crafted commit messages enhance documentation and minimize confusion among developers.

Key Points

Collaboration in Software Projects: Software projects typically involve multiple developers over long periods, thus necessitating excellent communication.
Significance of Commit Messages: Well-written commit messages can serve as a method of improving documentation without significant overhead, leveraging project history to answer future queries about the development process.
Examples of Poor Commit Messages: Ryan provides several poor commit messages from real-life scenarios:
- Vague Messages: Developer commits with phrases like 'What scripts? Why? How?', which provided no clarity or context.
- Indignant Tone: Messages revealing frustration without any mention of context were shared, leaving future developers confused about the issues faced.
- Meaningless Changes: A developer who committed thousands of lines of code without explanation complicated future understanding and maintenance.
- Confusing Code: Ryan recounted a rescue project where previous developers left messy commit histories, leading to extensive time wastage during code cleanup.
Examples of Good Commit Messages: Afterwards, McGeary showcases better practices:
- Effective, succinct messages that convey clear changes made to the codebase and the rationale behind them.
- A template for crafting good commit messages: Start with a verb, provide a brief summary, and include detailed explanations of the changes.
- Suggestions for action verbs that can help structure commit messages effectively.

Conclusions

Ryan emphasizes the critical role that well-structured commit messages play in software projects, urging developers to avoid creating a confusing mess akin to 'urinating on their projects.' With proper messaging techniques, the development process can be streamlined, leading to less time wasted and better overall communication among teams. He concludes with his contact information, inviting ongoing conversation and connection regarding these insights.

00:00:05.040 So this is a bit of a public service announcement: software projects are collaborative. They usually encompass many months or years and are touched by several developers along the way. Communication is key to any successful software project. Strong, well-written commit messages are one way to improve communication and documentation with very little overhead. The project history, plus a strong blame engine, gives us the power to answer future questions about what we were thinking at the time something was added or changed.

00:00:14.200 For some of you, I’m already preaching to the choir. For others, I hope I can provide some insights that you can bring back to your teams. And for the rest of you, I will show some bad commit messages on display. Before I start, I should mention this photo. These signs show up in the Commonwealth countries like the UK, Australia, and India. Apparently, they are a way of politely asking people to avoid improper acts in public, specifically to not urinate on the walls.

00:00:41.160 Let’s dive into some bad examples. I took these examples directly from client projects and some open-source projects. Here’s a story about a developer who spent several hours trying to get something to work. He obviously had trouble, but he littered the project with some messy history. It starts with a commit that is not very useful. It goes to subsequent commits that are equally unclear.

00:01:06.000 This developer's commit messages are vague, including phrases like 'What scripts? Why? How?' This is not helpful. We want clarity in our commit messages. At one point, the developer questions their own methods, saying things like 'Uhoh, need to learn how to use this.' This is getting silly. It's good to ask questions, but a commit should not be a question, it should convey what was done.

00:01:45.080 Here's another story about someone who was frustrated but left no context. We have no idea what he was annoyed about. He started with indignation and ended in despondency. In fairness, this person was struggling with integrating OAuth while using a third-party service, but unfortunately, the commit messages left many questions.

00:02:26.800 Another example is someone who unintentionally made many developers' lives more difficult. They committed thousands of lines of code with no rhyme or reason. Lastly, this one’s my favorite. I took on a rescue project where the previous developers were no longer around. The existing tests were minimal at best, and most were absent. I found a piece of code that was particularly confusing, which led me to a commit that had no relation to the core problem.

00:02:54.000 You might ask why I am so pedantic about this. Well, these commit histories caused the client many hours of headaches, questioning whether it was safe to remove unnecessary code. It’s a real waste of time. Now let's look at some better examples. I’m going to run through these quickly. I'm not claiming they are perfect, but they certainly reflect good practices.

00:03:41.640 Here are a couple of short messages that are effective. We know what changed and without looking too closely at the diff, we understand that a bug was fixed and what the underlying problem was. We also have some detailed examples that provide insight into the reasoning behind the changes. Then there's this one, which is particularly effective because it illustrates the developer's mindset at the time.

00:04:06.000 Here’s a quick template for what a good commit message might look like: we start with a summary, finishing with some details. I like to start with a verb, followed by a fragment sentence. Optionally, include a ticket from your issue tracker. In the detail, I suggest specifying why something happened. Here are some verbs for those who might be facing writer's block when crafting a commit message.

00:04:43.320 Lastly, the moral of the story is to please avoid urinating on your projects with lousy commit messages. I'm Ryan McGeary, and this is my contact information. Along with Jim Garin, we're the team behind BusyConf. I also run McGeary Consulting Group. Feel free to reach out anytime.