Commit Description as a Thinking Tool

In the pre-AI era, the author took considerable care in crafting lengthy commit descriptions for significant code changes. This process typically consumed five to ten minutes, dedicated to drafting and double-checking the message. The author's motivation behind this diligence was twofold: providing comprehensive information for readers and elucidating both the "what" and, more importantly, the "why" behind the changes.

By employing a first-person narrative style, such as "I did this because..." or "I am doing this until we...", the author aimed to facilitate easier comprehension for others, as well as future versions of themselves. This practice proved beneficial not only in refining the commit message but also in fostering deeper reflection on the code itself.

During this self-assessment phase, the author often revisited the code, dissecting the changes and evaluating the rationale. This iterative process occasionally prompted revisions, leading to improved outcomes.

The advent of agentic coding, where AI is increasingly responsible for both code generation and commit descriptions, has introduced new challenges. The debate surrounding the veracity of AI-generated code has intensified, with particular scrutiny directed at the readability and comprehensibility of AI-crafted commit descriptions.

These descriptions often lack the broader context that exists across various communication and project management platforms, and in some cases, extend beyond digital channels into offline discussions. Consequently, when an AI generates a commit message, it may inadvertently fabricate a "why" that does not align with the actual motivations behind the change.

This fabricated reasoning can lead to confusion and misinterpretation when the code is examined later.

To address this issue, the author advocates for the preservation of a personal touch in the commit description process. Despite the availability of AI-generated code and descriptions, the author emphasizes the importance of drafting the commit message and explanation independently. This approach enables a thorough examination of the AI's output, allowing the author to verify the alignment between the described changes and the actual code modifications.

Should the author struggle to articulate the underlying "why," it serves as a clear indication that the understanding of the shipped code may be incomplete or lacking. This practice aligns with a timeless adage: if one cannot effectively explain the rationale behind their work, it suggests a deficiency in their comprehension.

In essence, the commit description continues to serve as a valuable thinking tool, guiding the author through a self-reflective process that enhances their understanding of the codebase. Even as AI assumes a more prominent role in software development, the author underscores the irreplaceable value of human insight in ensuring the integrity and comprehensibility of the final product.