projects | blog

[all the things] [rss]

February 27, 2023 5:58 PM


I've heard that a lot of programmers sometimes get "in the zone". They're working on implementing something new, and they've got all these ideas in their brain and they're just pounding out lines and lines of code, and the hours just melt by. They don't want to get up. They just want to keep coding until they're done, even if it's past End-Of-Day.

I mentioned a few posts ago that I don't really get in the zone when I'm writing code. But I think the closest I ever get to feeling that way is when I'm done making all my code changes and I start making commits. Git commits.

I don't think I have strong opinions about too many things in the tech space, but I care a lot about commit messages. Every time there's a new dev on my team, and I review one of their PRs for the first time, I always point them to How to Write a Commit Message. I know I'm never going to get the hundreds of developers at the company to abide by these guidelines, but damnit I'm gonna try.

I rarely ever make a pull request with just one commit in it. I start with a gigantic diff, and I try to break it apart into smaller, easier to digest pieces. "Okay, first, I'll commit changes I made to the schema of this table, and then I'll make this change to the model layer, and then I'll work on the controller,..." When I make bug fixes, I start by adding a commit that adds a failing assertion, and I commit it by itself:

Exposes a bug in the code. This will fail as of this commit

The order matters too. If I made changes to five different files, what order do I want the reviewer to look at them in? I want to be able to guide the person, and not have them feeling overwhelmed because there are so many changes. I want them to know why I made certain choices in the code, and what parts of my change I feel unsure about.

The act of organizing everything helps me find places in my code that could be improved as well. Does this method need better documentation? Can I easily read this from top to bottom?

And I'll even throw in pointers for looking at a diff:

Look at this diff with the -w option, and you'll see that the only things I changed here were whitespace.

Use the --color-moved flag to see that I didn't add any new logic, just moved it from one spot to another.

And when I can't make something easy to digest, I'll say that too

This diff is kind of a mess, so I'd just recommend looking at the method in the file itself.

In the end, if I'm happy with everything, it feels like I've created something beautiful. At least to me.

Sometimes I wonder, is it really worth it for me to take an extra four hours just for committing? I know for a fact that some people I work with don't even read the commits. They just look at the full diff in bitbucket. And then I get a comment like this:

Why did you remove this line?

And in my head I'm thinking "Well if you read the commit message that went along with it, you'd know exactly why I removed it >.>"

But this scenario is slowly becoming less and less common.

A few weeks ago, everyone on my team was tasked to find an example of good documentation in the code. And one of my co-workers brought up my 30+ commit pull request, and said that even though it was large, it was very easy to follow. It was easy to see which parts of it were simple, and which other parts required a more thorough review. I think I spent a whole day putting those commits together, and it made me feel so good to know that it made a difference. For me, it was one of the most thoughtful comments I've ever gotten about my code.