To me, this is the real point of the story. If you are doing anything at all non-obvious, then eventually it will make no sense at all, so write down why you did it.
I think it would be good to ask yourself two questions every time you write a piece of code.
1. Is it obvious what this code is doing? (For example, i+=1 is always obvious, at least in regards to what it is doing.)
2. Is it obvious why I'm doing this? (If you're in a loop, i+=1 is pretty obvious as to the why as well, but elsewhere, it might require explanation... and you probably shouldn't be using the variable name i outside a loop, but that's not the point I'm trying to make here.)
For some idea of what this looks like, I've been working on a piece of code today that uses an external program through its API to load a file and make some changes to it. I didn't document the 3-4 lines it takes to load the file and get the object I need. Why? Because it's just how you load a file. Anyone could figure out that out from the documentation. It's already clear what I'm doing: loading a file. And why I would want to do that is obvious given the intent of the program: the whole program is created to perform some operations on files.
I do, however, document why I'm changing the working directory of the program to the folder the file is in. Because the program always saves to its working directory when you call Save from the API, which is not at all obvious or documented in the API.
For one rule (certainly not the only one): anything you had to figure out through trial and error is non-obvious.
It might be interested to collect some example of things programmers decided to or not to document and explanations for those decisions.
My experience over a long career of fixing bugs is that it just doesn't matter. Comment-free code doesn't tell you why it does what it does. "Well"-commented code devolves into lies over time. Hard bugs are just hard.
What does help is keeping the voodoo out in the first place by reducing the "non-obvious" bits to an absolute minimum. Which of course is isomorphic to saying that "great code has less bugs". Not exactly profound. But notably it has nothing to do with commenting or documentation, per se.
