Why We Don’t Document Code

By Deane Barker on September 6, 2013

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.



  1. oh my god: you are just talking about me in the recent time !; i have implemented an interpreter for an interesting new high level general purpose programming language, and that interpreter has ~ 36000 lines of java code (full of complicated algorithms, and a lot of usage cases) ! and (of course) i neglected documenting it for ~ 2 years, so when i decided it is the time to make it open source: i found my self in a BAD situation. so i’m trying now days to document the most important points of its working model !

  2. Sounds like a bunch of poor excuses to me.

    Yes, documentation is not the job developers want to have, but if you’re serious about a piece of code (especially when you know/hope others will use it in the future) it’s part of the task at hand.

    If your development is changing drastically every time you think about it seriously, it’s not yet stable, and it should not be distributed or put to use in production. If you’re thinking about a v2 rewrite, that means you have a v1 right now and that needs to be properly supported and documented.

    Exactly for 2nd and 3rd reasons you mention as excuses, documentation is extremely important, and you should do it as soon as possible. When do you want to know your architecture is a mess – early on or after delivery when you finally document it? When do you want to know your code sucks – how about when writing it, so you can turn it into something better?

    The solution? Document while you develop and stop moaning that documentation is hard: it’s part of your job.

  3. I agree with Mark above.

    If you can’t document it, it means you don’t understand it. If you don’t understand it, you have no business shipping it or even committing it to a shared repository.

    If you could document but decide not to, you’re a lazy bum. Sorry, no excuses. How do you know what you were thinking in 6 months? In one month? Hell, how do you know what you were thinking when you come in Monday morning? If you didn’t document it, odds are you don’t. So comment that code. Now.

    Lack of documentation is a bug. If while documenting it you realize the docs don’t make any sense, it’s probably because the code doesn’t make sense either. So fix the code, then document the fixed version.

    What about the embarrassment factor? If you leave a comment “I know this is crap but I’m doing it for reasons X, Y, and Z” then I know that you’re at least aware you’re doing something oddball and have a potentially good reason for it. If you have code that’s obviously crap (or doing something mysterious, or entirely incomprehensible, etc.) and isn’t commented, the only conclusion I can draw from the evidence available is that you’re a shitty programmer. So I’ll conclude that you’re just an idiot and curse you and your family name.

    There’s two kinds of developers: Those who properly document their code and lazy bums. I don’t trust code from lazy bums.

  4. This is the obvious reply, i know, but 99.9% of the time code should be self documenting. Good naming conventions, well structured code and ample unit tests should provide all of the information other developers need.

  5. Yeah. I document everything that I do all the time because I don’t suck at my job. Your laziness is a habit and you can just change the habit. You document while you code–not after. Factor that in to the time that you allot to any task. Yes, I only added 50 lines of code. Yes, that took 4 hours. Because I wrote docs and tests. Good code is expensive. It just is.

Comments are closed. If you have something you really want to say, email editors@gadgetopia.com and we‘ll get it added for you.