You've learned to write some code. You've read some blog posts and mastered the basics of git. Why are your code reviews still a huge altercation? It's not enough to write good code and slap it into a git repo. You need to carefully consider your git commits (and likely your pull requests as a whole).

Commit Contents

First of all, we probably need to talk about the actual content of your commits. By that I mean, what code is changing in each commit. There are some pretty simple guidelines to make good changes.

Don't break the build.

If your change breaks the build, it's obviously a bad change. In an ideal world, you should be able to walk back through your previous commits and they all work plus or minus a few features or bug fixes.

Don't change too much

Each commit should be focused on doing one thing. Fix a function. Add a UI element. Remove some unnecessary junk from the olden days. Just don't do these all at once. This way when you step through your history (which you'll be doing often either for code reviews or debugging), you'll be able to make sense of how things changed, which "coincidentally" segues right into our next topic.

Commit Messages

Raise your hand if your first commit went something like git commit -m ".". We've all been there. Unfortunately, we don't all grow out of it as quickly as we should, and when we do, we graduate to git commit -m "fixed some stuff", which isn't actually any better—it might actually be worse since it's more verbose without really conveying any more information. Some companies have very specific guidelines on commit messages. For instance, Meta was borderline overboard on the commit message spec when I worked there. However, in the absence of a defined message format, we need to be more disciplined ourselves. Let's talk about what we can do better.

Be specific.

If you added a UI element, your commit message should say so. Better yet, say _wh_ich element was added. Say where it was added. In some cases it may make sense to say why it was added. "Added UI element" is better than ".", but "Added submit button to contact form" tells us way more and really didn't take that much extra effort.

In the previous section, I talked about stepping through your history in code reviews and debugging sessions. Writing good commit messages means when you look though your history, you won't usually need to inspect the actual code changes to see what was happening. If you broke your changes into meaningful, atomic chunks, this is just the natural next step, and it will be so much easier. On that same note, if you find yourself needing bullet points to talk about separate entities in your commit message, then you need to go back and rethink your changes.

Use keywords.

This is an extremely underrated practice in the software engineering field, but it makes your messages look way more professional, and conveys a great deal of information at a glance. A keyword is just a note that gets tacked onto a message to tell you something about that change. I like to put them at the beginning of the message, so you see that info right away, but that's just preference.

More specifically I use keywords to indicate what kind of change we're looking at. My usual categories are "feature", "fix", and "style." "Feature" means I added something new in this commit. "Fix" means I fixed a bug. "Style" means no functionality changed, but I did move some stuff around. The style keyword is particularly important because it also serves as a reminder that you shouldn't mix in full file reformats in a bug fix that only needed a one line change. A commit message with a keyword might look something like "feature: added submit button to contact form".

BONUS

If you followed this advice and are making better commits now, I have a nice bonus for you. Whether or not you use this bonus, it will serve as a great example of how useful good commits can be.

Here is an awesome little tool I created to search through your commit history and automatically make a change log from your commit messages. It builds with Poetry (which really deserves its own post), so it's basically plug and play. If anyone gets any real use out of this thing definitely let me know. I'd love to hear about it.

UPDATE: It's been brought to my attention that unbeknownst to me, this keyword-oriented convention already exists and has a name. Check out conventional commits for more info and the full spec.