Communicating Intent Through Git

by Josh Freeman

In the talk "Communicating Intent Through Git" at RubyConf 2015, speaker Josh Freeman emphasizes the critical role of communication in software development, specifically through effective use of Git. He starts by discussing the significance of storytelling in conveying ideas and how excessive compression of information can obscure the intended message. Freeman explains that while Git efficiently tracks changes, it often neglects the vital question of 'why' changes were made.

Key points include:
- The Importance of Communication: Freeman recounts his early reluctance to communicate as a developer, only to realize that effective team collaboration and communication drastically improve productivity.
- Effective Git Usage: While Git captures the who, what, when, and where of changes, Freeman argues it falls short of elucidating the motivation behind decisions. He believes that software development is the culmination of numerous decisions, and understanding 'why' a feature was added or changed is essential.

- Commit Messages: He encourages developers to abandon the simplistic 'git commit -m' approach in favor of detailed commit messages that start with an imperative verb and provide context about the change, addressing not just what was changed but also why it was necessary and how it fits within the larger codebase.
- Comments vs. Code Clarity: Freeman argues that if a piece of code needs comments to explain its function, the naming of that code likely needs improvement. Clear and concise naming should reduce the need for comments, which often become outdated.

- Using Git Blame/Thank: He suggests rebranding the 'git blame' feature to 'git thank', promoting a mindset of gratitude towards past contributions while emphasizing the importance of maintaining comprehensive commit histories that document reasoning behind code changes.
- Pull Requests: Freeman highlights that pull requests serve as important communication tools. He encourages developing meaningful commit messages and small, manageable pull requests to facilitate easier code reviews.
- Continuous Improvement: He concludes by reminding developers to document their processes and decisions, enabling future maintainers to understand prior changes without unnecessary guesswork.

Overall, Freeman champions the belief that meaningful commit messages and effective communication practices are vital for collaborative software development. The discipline of consistent and detailed documentation can lead to clearer, more maintainable code and better project management.

Ultimately, the audience is reminded that clarity—not just in code but in the documentation around it—is essential for successful software development.

00:00:15.279 Alright, let's talk about Git. My name is Josh Freeman, and I am a software developer here in San Antonio for Groc Interactive. We primarily turn tacos and caffeine into software, and we have a pretty good time with it. Today, I want to share some stories; stories have power. I love a good story—the narrative that the author tries to tell, the context in which these stories are told, and the motivations of the characters involved.

00:00:29.119 This talk is not going to be too technical. There will be some how-to information, but mostly we're going to focus on the communication process that we undertake in software development. To illustrate this, we'll start by discussing compression.

00:00:44.140 When we look at compression in video, music, and pictures, we see that a certain amount of data compression is acceptable. However, when you're trying to communicate something textually, compression is not such a good idea. I want to prove this point with some highly compressed headlines from a story you may know.

00:01:07.760 First headline: "Local farmer's family murdered by military police; nephew, 21, sole survivor." Second headline: "Nephew of murdered family leaves home to join separatist force." Third headline: "Farmer turned pilot destroys key military facility." At this point, who knows what story I'm talking about? Star Wars.

00:02:05.820 Compression can be beneficial in many respects, but if you compress too much, you lose much of the richness of the information and the narrative you're trying to convey. This is what I want to discuss today, especially in the context of working with Git.

00:02:18.010 If you enjoy XKCD, you may appreciate this comic. I'm going to assume that you understand the basics of Git, as this will be more of an intermediate talk focused on leveling up your commit messages.

00:02:35.860 As a quick refresher, why do we use Git? First, using FTP and email to transmit files is not efficient. Secondly, versioning of software is something we find we need repeatedly. For instance, if you work with designers, they often end up with file names like 'composition.psd', 'composition_final.psd', and so on. Even designers recognize the need for iterative improvement; software development is a living, evolving process that grows alongside our understanding of the business.

00:03:04.180 Git functions as a communication tool. When I first started with software development around four or five years ago, I found myself in a position where I didn't want to talk or work with people. Software looked attractive to me then; I could sit at the keyboard all day long with minimal interactions. However, I quickly learned that to be effective in my job, communication is essential. Attending this conference demonstrates the importance of engaging with people, whether they're your teammates or clients, to achieve something productive.

00:03:32.769 Git is one of the most important tools we have, yet it's often used the least effectively. While it forces us to answer the who, what, when, and where, it never requires us to ask why. Software has three audiences: the author (ourselves), the team we are working with, and the future maintainer, who may or may not be the same as us. Effective communication through both code and version control is crucial.

00:04:22.229 Software is the outcome of countless decisions made over months and even years. We introduce features, clarify methods, and alter behaviors, but we should always be able to provide answers to why these changes were made. There are two hard problems in computer science—naming things, cache validation, and off-by-one errors. Today, we’ll focus on naming things.

00:05:00.930 I align with Bob Martin’s philosophy that comments are an apology. If you find yourself needing to write a comment to explain what’s happening, it likely means you haven’t chosen a name that clearly conveys that information. While comments have their place, if you find yourself writing many comments, I suggest you need to choose better names.

00:05:50.130 The only source of truth is what the code itself says. If there's ever a divergence between your comments and your code, the code is always the correct version. We've all experienced comments that drift and no longer reflect the code accurately. About a year and a half ago, I came across a piece of jQuery code where the comment block was two to two and a half times longer than the actual code—and it didn’t clarify what was happening.

00:06:57.160 In fact, if you know the jQuery API, it's quite obvious what is happening here. So does this method name even describe what is going on? I don't think so. We shouldn't need a comment to explain what a function is doing. In this case, the only information I would want in the comment is perhaps the parameters for automatic documentation generation. The rest of the information was merely my learning process and could have been better captured in a commit message.

00:07:39.700 If you find yourself writing extensive comments just to explain small bits of code, your commit messages may resemble this: 'I never get it right initially, and I end up frustrating my team.' When we start using Git, we usually feel enthusiastic, but over time, our comments and messages tend to lose their value. We begin with good intentions but quickly stray.

00:08:29.919 This issue often arises when you're working alone and don't expect the code to be public. So how do we fix this? First, we need to stop using the 'git commit -m' approach for commit messages. This one-liner gives the impression that the whole patch needs to fit into one line, making it unwieldy and unreadable.

00:09:18.100 Instead, just use 'git commit' and drop into your text editor of choice—whatever makes you comfortable. To summarize, I recommend checking out Tim Pope’s article, which discusses writing more useful commit messages. First, write in the imperative form and keep the message under 50 characters. This practice aligns with Git's conventions for automated messages generated by 'git revert' and 'git merge'.

00:10:07.040 Next, provide details about what is happening in the next line of your commit message, keeping it under 72 characters. This format is beneficial for anyone who typically works in the terminal and views their Git messages there. The specifics of your audience will matter, but generally, it's best to keep them concise.

00:10:56.240 You should answer a few critical questions in your message: Why is this change necessary? Are we fixing a bug, adding a new feature, or addressing a client request? How does this impact the rest of the code? Does it have side effects? Lastly, provide references or links to resources, especially since we all spend considerable time researching solutions online.

00:11:56.490 Now you've done all this work, and your commit messages are useful. When do they become even more valuable? When you're using the blame feature in Git. 'git blame' allows you to look at specific lines in a file and see who made changes and when.

00:12:03.920 However, the term 'blame' can sound accusatory. I prefer to think of it as 'thank'. So, whenever I find that a teammate altered something that isn't working, I can 'thank' them for their contribution. This was evident recently when a teammate asked me why we were using an older version of an AWS SDK. It took me some reflection to remember that it had to do with dependencies on another gem we were using.

00:12:54.350 All the time I spent debugging that issue was now forgotten because I didn't put the information into the commit message or the code. A similar situation arose while using gpg to execute system commands; I realized we had been creating vulnerabilities due to interpolation issues. After I discovered the shell words feature in Ruby, I documented it well in my commit message.

00:13:56.870 Another example came from a client email. We all receive emails asking us to make changes. Don't let that information fade away into the ether; include meaningful snippets in your commit messages. Additionally, avoid using ticket numbers and instead provide full URLs, so the context isn't lost, especially if your team ever switches ticketing systems.

00:14:58.570 In terms of searching within commit messages, I find myself looking back at previous work, particularly for things like favicon generation, and being able to pull up past commit messages can save time.

00:16:06.560 Let’s work through creating a new project, possibly with Bundler or Rails, and starting with a solid first commit. It’s an excellent idea to begin with boilerplate code that is clean and clear.

00:16:39.580 Next, we might want to intentionally create an incomplete implementation to highlight errors in our approach. When you observe issues or errors in your initial attempts, it's essential to trace this back to specific changes, affecting the naming conventions and method structures. If there are spelling errors, note that they might not require extensive explanations unless it adds significant context.

00:18:57.440 After introducing mathematical functions, we see that there could be improvements in how we handle addition. Ensure you're staging the appropriate changes when making corrections.

00:19:30.370 When adding patches, for example, with 'git add -p', you can manage your changes more effectively and mitigate the risk of accidentally committing incorrect or unnecessary adjustments.

00:20:11.640 Correct coding practices involve breaking your changes into manageable chunks, which simplifies reviewing. If you've made a mistake or need to rename functions, don't hesitate to perform a rebase. When discussing changes with your team, you can clarify any issues like naming conventions and provide organized feedback.

00:20:59.110 Now, let's delve into pull requests and the importance of clear communication when presenting your code for review. In my early experience with code—particularly moving from doing work with PHP to Ruby—I found myself in situations where there was confusion simply because communication was limited to text.

00:21:42.270 Establishing rapport with your team is vital for effective collaboration. Hold on, can we talk in person sometimes? Hearing tone and providing clarity becomes critical when discussing sensitive topics related to code.

00:22:58.780 At Groc, we emphasize understanding core business domain problems. We are not just coders looking to make things work; we aim to solve actual problems. Code reviews provide a crucial opportunity to verify that everyone understands the problems being addressed.

00:24:46.680 As we conclude, it's essential to reiterate the importance of utilizing meaningful commit messages. Avoid shortcuts like 'git add .', as these can obscure intention and message clarity. Learn to implement patches and keep things organized.

00:25:42.230 In your pull request process, keep changes small and focused to enhance review efficiency. Documenting changes and utilizing helpful tools like gifs or images can significantly improve communication.

00:26:41.460 The takeaway here is two-fold: Commit messages should have meaningful context and should aid in understanding the purpose of changes. Always prioritize clarity.

00:27:04.320 Lastly, you should aim to avoid large pull requests as they increase complexity and the likelihood of miscommunication. We live by the motto that if it’s not on GitHub, it doesn’t exist. Regular commits help keep the scope manageable.

00:27:56.450 Create short-lived branches for features and bug fixes. This discipline fosters better project management and prevents overwhelming changes from piling up.

00:28:56.210 Thank you for being here, and I hope these insights have been helpful.