Documentation

I was reading a list of things a programmer does. Lists usually don’t repeat themselves; each item is unique. So I became very confused when I read two consecutive items: “documentation” and “commenting your code.” I looked back and forth in bewilderment, trying to figure out why there were two identical items in the list. Of course, the letters are very different, and one item had three words while the other had only one.

I finally realized my mistake, and became quite pleased with myself that I consider these two things so intrinsically related that they defaulted to being the same thing in my mind. After all, we’re all trying to achieve that great ideal called “self-documenting code.” The more I thought about it, however, the less sure I was that this was a good mental association.

I can’t deny the usefulness of formal documentation, especially when I have needed to use some library whose source code I do not care to examine. And I’d love to always write code that perfectly communicates the code’s purpose and reason for existing. But I have struggled enough with trying to name things, and with human communication in general, to know that words don’t perfectly communicate meaning; they’re just a less unreliable method for attempting to do so. The more words, and the more meaning is communicated, the clearer the communication.

So name your functions and classes well, write your comments, and generate your docs. All of these have an appropriate use and all are necessary.