[pjungwir]

Some day I'm going to write a blog post about this, but I think comments are like commentary on a chess game. Sure, I can read Nf6, but I want to know so much more. Like chess, computer code leaves a lot unsaid. Perhaps I did it this way for performance implications, or an edge case off in some other file, or to work around a bug in a 3rd-party library, or for the sake of pattern x, or . . .

As a mediocre chess player, I can read the notation for two chess games and appreciate a lot, but I doubt I could tell the difference between a game played by players rated 1800 and one by 2400s. Programming seems the same way: you write comments so that other engineers don't have to be 2400s to understand the hidden implications.