de tomKronieken

Glen finds out about the documentation problem. The questions he poses seem to be quite right, but imagine the programmer writing that line. She is busy keeping 15 threads on various levels in her head, and then she has to write a comment for a method. At that moment, her head is already full, and she really isn't capable of starting to imagine which alternatives are possible for another reader.

Another way of expressing myself: when writing code, everything seems to be pretty obvious to you. You expect everybody to understand the same thing, especially for trivial getter methods like this one. Why bother trying to guess a reader's context?

Of course, that "triviality" almost always bites somebody, and most of the time, it is the programmer herself. It always comes as a surprise if you have to read your own code a couple of months later: "When writing that comment, I clearly remember thinking 'this is so damn obvious', but, man, what does the damn thing do?"