[bunderbunder]

> The right place to document [performance] hacks is a commit message.

This advice strikes me as patently insane.

Serious performance hacks often involve subtle interactions among different parts of the code. When that happens, properly documenting them requires explaining what's going on in a line of code, for every line of code, right next to that line of code. Just sticking a wall of text somewhere else entirely and leaving it up to your successor to go find it and figure out how the explanation cross-references with the code is not an adequate alternative.

[arjie]

Likely to be using a workflow that uses `git blame` or equivalent to understand the context of code. The problem that is intended to fix is that comments don't stay in sync with the code they're commenting about. The problem it introduces is discoverability. You have to search to see where this code came from in order to understand it. That isn't going to happen unless you're disciplined. And we're all undisciplined at some point or the other.

[_delirium]

I only find blame-type tools useful for discovering either recent context, or context of rarely-touched code. They typically only easily show you the most recent change to a line of code, though you can sometimes dig through older changes in a kind of per-line commit history. So older changes get more and more buried under an accretion of more recent ones. To find the commit message discussing a performance hack from 8 years ago, you'd have to wade through all the more recent commits that also touched those lines of code (refactoring, fixing unrelated bugs, fixing library bitrot, etc.). I'd rather that important context stay right there in the code, not get buried among hundreds or thousands of other commits.

[wellpast]

I've worked on teams that emphasize commit logs as a place to keep significant information about the code.

This inevitably coincides with a "minimize change deltas" mentality to development because else the commit history gets confused. Continuous refactoring goes out the window and so does the soundness of your code base.

The code should speak for itself, period. It should be clear and sound before and after each transformation it undergoes. And there should be no limit to what kinds of transformations it undergoes.