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 !"