Building Helpful Commit Messages

Using a VCS (Version Control System) is important in any modern software development environment. I still can’t believe that both application and database developers are using a VCS at less than the 95% level, but surveys constantly show this. I’m not sure if this is because of laziness, ignorance, stubbornness, or something else, but it’s a bad idea. Start using a VCS. Talk to your management, and let them know Git is free and can be run on premises, much like a file share for code, except it’s better.  Even if you hand craft scripts (or use the SSMS GUI), just start saving those scripts in a VCS.

There are lots of tutorials and examples of how to use git (or any VCS), and this is a skill you want to build over time. To start, just learn to build a habit of committing code to the repo as you make changes. This is fairly easy, but there is one skill you need to develop over time: how to write a good commit message.

When we commit code, we usually need to enter some comment. This is a bit of an art, and should be designed to quickly convey information to the next developer (who may be your own future self). While people may have their own view on what to include, my thought if usually to include the “why” of the commit. This helps me to go back later and understand what I was thinking. I don’t need “what” was changed, because a quick diff of the file will explain that. If possible, I like to relate a commit to a specific request, like a Work Item, a help ticket, or some place that describes the requirements in more detail.

I ran across a nice post that describes the art of the commit, and I think there are some good ideas here. Certainly being brief and understanding that often your message is a headline is good advice. The most important parts of the post, for me, are the need to understand that I’m working with others, and it’s important that my message help them and vice versa.

Learning to use a VCS is a critical skill for anyone working in the technology field. We know most application developers need this, and slowly I find more database developers doing the same. However, as we move to GitOps and Configuration and Code, as compliance becomes more impactful with more auditing requirements, as we try to do more with less, the infrastructure staff and others need to learn how to capture their changes in a VCS as well.

Do yourself a favor and start learning how to use a VCS. Git makes it easy or you can play with Azure DevOps in the cloud. Just start saving some files and building skills. Your career will thank you. Learn to write good commit messages and your team will appreciate you.

Steve Jones


About way0utwest

Editor, SQLServerCentral
This entry was posted in Editorial and tagged , . Bookmark the permalink.