Before the AI era, I wrote beautiful lengthy commit descriptions (or commit bodies) for important changes. It took me concerning five to ten minutes to outline and reread them to create certain I didn’t young female item important. I did that for multiple reasons.
I wanted to contain all the helpful data so readers wouldn’t have to hunt for it in multiple places.
I wanted to explain what and, additional importantly, why. The “what” summarizes the changes that are mostly self-explanatory, but it gives a starting item for explaining the “why.”
Sometimes, I compose it in archetypal person, akin I am example a communication for someone: “I did this because…”, “I am doing this until we…” etc. I afterward go onward and explain why, so that it is easier for others, and most considerably for my forthcoming self, to comprehend why we made that change.
It was a fine exercise. It wasn’t fair concerning penning the commit communication and description. The penning procedure itself helps me indicate on the code I wrote. I reread the code and summarize the changes. During that process, I lean to re-evaluate the decisions, and sometimes that leads to a distinct or improved change.
Now we are in the era of agentic coding, anywhere everything from code to commit descriptions is written by AI. There is a huge conversation on whether we should peruse the AI-written code, and how difficult that is in conditions of readability. The part I discover difficult is study and understanding AI-written commit descriptions.
Agents can compose commit messages for the changes they make. But they may not have the complete environment that is dispersed throughout distinct communication and project administration tools. Some of those power be offline too. When the AI doesn’t cognize the ‘why’ part, it comes up alongside its own reasoning. I discover that dangerous. When we peruse that later, it may not create sense, since the genuine logic was entirely different.
One apparent resolution is to provision the delegate all the environment it needs, through conversation or tools. This helps to fix the issues alongside fabricated reasoning. The delegate can now explain the “why” clearly.
But this doesn’t fix the another problem. The delegate alongside the correct environment volition compose a convincing commit message. But lone I can verify if the code does what the clarification says. So, current is item I do:
Write the commit communication and clarification myself.
Here is why.
Writing a commit clarification myself helps me to indicate on the changes AI made. It is additionally a way to inspect if everything is as intended. If I cannot explain “why,” I am shipping item I don’t understand, which volition be difficult to explain or fix if it breaks later. It goes rear to the old quote. If you cannot explain it, you did not comprehend it. The commit clarification again plant current as a thinking tool.
Some parts, akin “I am doing this until we…”, are impermanent decisions alongside exit criteria. We sometimes set exit conditions, and AI cannot infer them from code or another tools since they are normally not written downward anyplace since they appear too apparent to mention. But penning the commit communication forces me to complete that sentence, and it helps forthcoming readers decide whether to keep that change.
The delegate can compose the code and the description. But penning why is anywhere you discover out whether you comprehend what you are shipping.
