Self-documenting Code

There are a lot of people who follow the school of self-documenting code, some of whom I respect as some of the best programmers I have ever met. On the other hand, in my practice, I have found that self-documenting code doesn't exist in my little world. Moreover, I can't help but think, if people really can write self-documenting code, then why do we have papers where people talk about their code, or why do we have developer documentation at all? Why do we have API documentation? Why do we have blog posts about our code? To me, if we really have self-documenting code, then we should be expecting to see blog posts of nothing but code, and that should be sufficient for us. Is it? I've certainly not seen an effective blog post, paper, or program that was entirely, completely, without comment or prose. Usually it is always associated at some point with comments. More commonly, the code is almost secondary, and the prose takes a front seat. If code can really be written in such a self-documentary manner, then shouldn't we have code-blogs? Why are we writing in English?

To me, this gets at the heart of documentation. I just don't buy self-documenting code. I do buy clear, concise, and self-evident code, but that is different. There are so many contextual elements about a program that a program can't tell us, and that's why we have papers about that code, and blog posts, and the like. We have natural language for a reason, and we should use it to its best effect when using code. However, we should not rely on prose where the programming language is the better way to communicate an idea.

The union of prose and code makes more sense to me than having one or the other. Maybe that's why I like literate programming so much.