If you're newer to reading code changes, this is one choice that wastes time fast: walls of comments, or commit messages that explain the decision? I pick the second. Long comments often repay bad design debt. Long commits preserve the reason. [C002]
A comment sits beside the code. A commit message is the note attached to the change. The first often repeats what the code already says; the second is where I want the missing part: why this changed, what tradeoff I picked, and what I chose not to do.
That rule got sharper for me after two style references said basically the same thing. Git's patch guide treats the log message as part of the work because future maintainers need the why. Google's C++ comment guide pushes against comments that just restate obvious code.
This is not "never write comments." I still want comments for API promises, weird edge cases, and sharp corners. The target is the subtitle-track version of comments: line-by-line narration that exists only because the code is hard to read.
A change is not worth reading because it lists more detail. It's worth reading if it changes your next decision. [C001]
So my rule in a docs-and-code-review context is simple: if a note only repeats the code, rewrite the code. If the reason will be lost in three months, put it in the commit and make it easy to find later. Share that rule with the next person touching the file.