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.
