When you read through a part of your system that you've either never seen before or have forgotten how it works, do you also read all commit messages for all of that code? I'm asking because that's the only way I can imagine one can learn about the edge cases and surprising consequences in non-trivial systems if you have a rule about not using comments to explain them.

No, I do a git blame, and see all the relevant commit messages.

If there's not 1 line of code from that commit remaining why is it relevant?

If something looks weird still - I go back to the commit that created this part of code and git blame that. I don't remember a case where I had to do 2 steps like that.

BTW we have a rule of putting JIRA ticket numbers in commits, that makes it even easier to find out. You can see the whole discussion that resulted in the code you try to understand, test cases that you don't want to break with your new changes, etc.

>No, I do a git blame, and see all the relevant commit messages.

sounds great until there's a refactor (including moving code around), then all the "comments" get buried.

It's a bit humorous that often the same people who insist the code should be enough documentation follow that up by clarifying that git, of course, supplies the rest.

So something entirely outside the codebase, which may or may not be available to the person who needs the information, and which may or may not need to be extensively searched through years of history to find the relevant commit message, which may or may not be sufficient to explain the code... is better than having a comment in the code.

Git blame is great. But having to look at all commit messages over, say, a few hundred lines of code just to know about standard pitfalls does not sound efficient. Edge cases are not just in the places where code is obviously doing something odd. Sometimes they hide in seemingly normal looking code - the kind of code you may not think it's worth diving into the commit history for.