DEV Community

Discussion on: How I Write Source Control Commit Messages

chilcutt profile image
Kyle Chilcutt

Rule #3: Good Messages Explain What, Not How or Why

One thing the consider is what the benefit of the commit message will be long-term. In the future, when the context is no longer fresh in your team's mind, you might be debugging an issue or building code based on the code in the initial commit. For me, I'm much more often asking "why is this here"/"why is this like this" than "what does this do" (because I have the context of "what does this do" from reading the code itself).

I often find myself pleasantly surprised when I'm debugging an issue with some code, say to myself "what was I thinking", hit git blame/git show and immediately know the context.

I think the card number is definitely great, but I don't think a distilled explanation in a commit message is a a waste of time either. Another small nuance is that the commit message is written in your own voice with your own understanding of the problem, at the point in time that you've just written the code, so you're in a much better place to write a technical description of what you've just done (in my experience, finished code often deviates from the plan).

It does take longer to write the commit message, and I agree that it takes a lot to move a team to this practice, but I can personally vouch for the benefits!