Rule 10. If you can - comment in commit messages instead of statically in code.
When you do git blame you get commit message for each line of code. You can see what ticket changed it (there will be reasons why it changed hopefully), what it was before, what other things changed with it. This is incredibly useful, much more useful than static comments in code. But you have to help yourself by writing good commit messages and making small commits that don't mix many changes into one. If you fix whitespace or some stylistic stuff - don't commit it in the same commit as your business logic changes.
The best things about comments in commit messages is that they are automatically changed when you change a line of code in the next commit. They are never outdated and are never lying to you (regular static comments often do). Git blame should answer "why is each line of code here right now". Static comments answer "what somebody at some point thought was important in this general region of the code".
Often companies want you to adhere to their commit message standards that make it harder to write good commit messages. For example with git they will say "[task number] one line 80 char description"
You can still write a good description and have git show it correctly in one-line format if you do:
[task number] One line 80 char desc.
The rest of a good descriptive commit message.
As many lines as you like....
1) I can’t see “git blame” in my code review. Don’t make me check out the branch to review your changes.
2) If we refactor the code (say, extract a new class wrapping the functionality) then the explanation in git becomes much harder to find. If it’s a comment you can just copy it over.
You should explain the change set in your git comments too, but at a different level of abstraction - why is this whole set of changes being made? What problem is being solved? What’s left to do? Etc. this stuff can’t usually be associated with a particular line of code.
So inasmuch as you are arguing for good commit messages I strongly agree. But I disagree that this should be at the expense of good comments in your code.
You shouldn’t need this. The commit message should clearly explain any non-obvious changes (and ideally there should only be one). If there is a historical context, the reviewed commit message should include it (including links to past commits in whatever repo hosting service is used).
> refactor
If there is a refactor the reader can skip past the change in blame. This does become slightly more complicated when code is moved between files, but most repo hosting services make this fairly easy.
I don't like this idea. Nobody will read your comment in this case. I prefer comments to be visible by default without having to run extra tools. Also, usually a commit adds many functions and classes and it's difficult to describe them in one message.
When you do git blame you get commit message for each line of code. You can see what ticket changed it (there will be reasons why it changed hopefully), what it was before, what other things changed with it. This is incredibly useful, much more useful than static comments in code. But you have to help yourself by writing good commit messages and making small commits that don't mix many changes into one. If you fix whitespace or some stylistic stuff - don't commit it in the same commit as your business logic changes.
The best things about comments in commit messages is that they are automatically changed when you change a line of code in the next commit. They are never outdated and are never lying to you (regular static comments often do). Git blame should answer "why is each line of code here right now". Static comments answer "what somebody at some point thought was important in this general region of the code".
Often companies want you to adhere to their commit message standards that make it harder to write good commit messages. For example with git they will say "[task number] one line 80 char description"
You can still write a good description and have git show it correctly in one-line format if you do: