Why We Don’t Document Code

By Deane Barker • September 6, 2013 • 4 min read •

Author Description

Sometimes we don’t document for valid reasons, not just because we’re lazy.

AI Summary

This post argues against the necessity of code documentation, emphasizing that well-written code should be self-explanatory. The author suggests that excessive documentation can become outdated and emphasizes the importance of clear coding practices over traditional documentation methods.

Documentation is always the last thing anyone wants to do. In general, we all hate it, and software we wrote – even software that’s not one-off, but is specifically intended for the future use of other people – generally never gets documented.

Right now, I’m sitting on a software library that I wrote which painfully needs documentation. But I haven’t written it. I’ve been encouraged to write it, and it sorely needs to be written, but I…just…don’t.

I got to wondering why this is. After a week of soul-searching, here it is, for better or worse:

Code often evolves so quickly that it’s a moving target, and you never hit a point when you think it’s stable enough to document it. Open-source projects, especially, as always in some state of amorphous completion. “I’ll document it just as soon as I rewrite the whizbang interface, because what’s the point of documenting something that’s going to change so much?” The day when it’s stable never comes, of course, because you keep hacking. If you stop hacking, then it probably means you’ve stopped using it, making documenting it all the more pointless.
Attempts at documentation often turn into massive hack sessions. When you have to explain something to someone, you often come to understand how confusing it is. The attempt to explain it is a form of the rubber duck method of problem solving – verbalizing your architecture makes you realize how screwed up it is, and you set about to fix it before you document it (which, of course, you never come back to…). And these changes aren’t simple. Rather, they’re usually large-scale, architectural changes where you’re moving big chunks of the code around to make things “more understandable.”
You know your code is crap, and you don’t want to admit this by writing anything down. We all write bad stuff, but when you document it, you’re essentially admitting to it. Your hacky workaround is no longer hidden in some compiled method, but is right there for everyone to see. And by writing it down, you sort of just signed a confession: “Yes, I wrote that code. And, yes, that is how it is designed to work. [looks down in shame] I’m so sorry.”

Is there a solution to this? I don’t think so. If there was, I suspect we’d have found it by now.

Now, if you’ll excuse me, I need to get back to avoiding documenting some code.