I've often heard that the commit message should describe why I'm making these changes. And I think I agree with that. However, I've also often heard that inline comments (i.e. comments in the source code) should tell why the code works in this particular way instead of what it does.

So, when should I put the reasoning in the commit message, and when should it be written in an inline comment? Is there some rule-of-thumb or best practice that can be applied?

CodePudding user response：

Typically, one uses inline comments for matters which are necessary to understand the code. For example, if there is a tricky algorithm or subtle behavior, that should be documented in a comment, so that the reader can look at and understand the code when looking at a single revision.

You would use the commit message to explain the rationale for making a change, including why one alternative was chosen over another. For example, if you've chosen one algorithm over another, say, for performance reasons, that belongs in the commit message. You should also document things like the problem or idea which motivated the change to help explain to future readers why your change was valuable.

The difference is ultimately that in the former case, you want it to be visible while reading the code, and in the latter case, you can expect the interested party to look through the history.