I guess our company is doing something right because it’s been nice to see all the AI PRs that have details about the why in them rather than just commits with “fixed bug with [class]”

I'm really sad that after 20 year we still have to explain that commit message is not a summary of code modification.

Commit message is here to gives information's that are not visible in the diff. The context, the side effects, the decision that were made, etc... All of this cannot be generated by LLM.

Why a commit message and not a comment for that?

Could be a comment indeed. It's hard, or even impossible, to clearly decide where to put an information. There are some guidelines, but no absolute rules. Commit messages, comments, API docs, tickets, wikis, etc... all of them serve different purpose.

• Comments are here to explain an implementation detail when code cannot be self-explanatory. They live as long as the code live (and are unfortunately not always updated). They are used when a developer arrives on that line of code.

• Commit message are here to explain why something has been added/removed. What happen before, what happen after, why this solution was needed. They are tightly couple to the diff and generally don't contain generic high-level information (unless commit is a design or architectural modification). They are used by the reviewer and 5 years later by someone that do a git blame to understand why this line was introduced and what happen if I remove it.

• API Docs explain the behavior of an API, as seen from the outside. They should not explain the implementation, nor explain in which case and which part of the system they are used.

• Tickets explain a user request. They detail who request this and for what purpose, but only from user point of view. No implementation detail.

• Wikis are here to cover your ass so you can say "See, it was written in the wiki !"