sourmìlk wrote:I compulsively do not comment unless I know that other people will be looking at the code.
My problem with this thinking, even if it's completely correct in the literal sense, is that "me in 6 months" is almost guaranteed to be another person.
One of my proudest moments from coding occurred when the following happened. I got some code from some other people. It was kind of complicated, but necessarily so, because we were trying to use an API that did what we wanted, but getting the answer out took some work.1
Figuring all this out the first time took probably 30 minutes or an hour of me and a colleague looking at the code. I wrote up a description of this process in a nice long comment.
About 8 months later, I came back to that same code so I could change something. And while I have no doubt that I'd have had a much simpler time figuring out what it did the second time around, that comment I wrote made it completely trivial, as there was nothing left to figure out.
Anyway, I prefer self-documenting code when they do the same thing. Like I'd never do int x; // number of moons of Jupiter
or something like that. But self-documenting code only goes so far.1
To make this a bit more concrete, it's about accurate to say that we were building up a string, but what we had was a callback function that, when called, we'd append another letter to the string. But some letters were computed based on the result of two successive calls. So we had to keep around some auxiliary information from the first call to use in the second, then detect whether we were in a "normal" case, the first call of one of these special cases, or the second call of one of these special cases. (I also kept around some additional state to sanity check that the callback was giving us things in the right order.)