Let’s talk about self-documenting code

You think your code is self-documenting. That it doesn’t need comments or Doxygen or little diagrams, because it’s clear from the code what it does.

I do not think that that is true.

Even if your reader has at least as much knowledge of the programming language you’ve used as you have, and at least as much knowledge of the libraries you’ve used as you have, there is still no way that your code is self-documenting.

How long have you been doing your job? How long have you been talking to experts in the problem domain, solving similar problems, creating software in this region? The likelihood is, whoever you are, that the new person on your team has never done that, and that your code contains all of the jargon terms and assumptions that go with however-much-experience-you-have experience at solving those problems.

How long were you working on that story, or fixing that bug? How long have you spent researching that specific change that you made? However long it is, everybody else on your team has not spent that long. You are the world expert at that chunk of code, and it’s self-documenting to you as the world expert. But not to anybody else.

We were told about “working software over comprehensive documentation”, and that’s true, but nobody said anything about avoiding sufficient documentation. And nobody else has invested the time to understand the code that you just wrote that you did, so the only person for whom your code is self-documenting is you.

Help us other programmer folks out, think about us when avoiding documentation.

7 Replies to “Let’s talk about self-documenting code”

  1. I’m afraid this one falls in the same category as tabs vs spaces, so doubt anyone will ever win the argument. But to play Devil’s Advocate, consider the following:

    When was the last time you actually read extensive documentation in depth, rather than just looking at the code to figure out what was happening?
    When was the last time you read documentation that was wrong, or didn’t tell you what you needed to know about what it was documenting, and thus ended up going to the source (literally!)?
    Regarding the statements about expertise in the post, will any documentation that I write bring an non-expert up to a satisfactory level to make changes, or understand the code? Ie if they don’t understand the code, can you really explain the code to them.

    Personally, I don’t use a lot of documentation myself. I never state the bleeding obvious, ie, repeat what the code literally says. I would use high level documentation, to give the big picture. It can be useful to see how things fit together. The last usage is exotic code, ie, hacks or bug fixes which are far from self documenting.

    But excessive documentation often obscures the code IMO, especially if the code is straightforward enough to understand on its own. And your documentation doesn’t need to compile, so it is very quickly misleading.

  2. I find that most of the people who think/say “my code is self-documenting” haven’t had to live with their own code for very long, let alone code from others. I’ve been working on the same app on a variety of platforms, both mobile and desktop, for over 20 years. I heavily rely on my comments to remind me why I wrote the code the way I did 15 years ago so that I can understand how to best translate it to a new language or platform today. Or to help me understand how best to extend it with new features without breaking subtle interactions or violating assumptions.

    Six years ago, my programming/business partner of 27 years died unexpectedly. He was a prolific documenter. It’s not unusual for me to open up a piece of code he wrote and spend 30 minutes reading the short novel he’s written at the top of the file describing the alternatives he considered, the benefits of doing it the way he did it, and where the opportunities are for improvement. That information is priceless.

    Good documentation is no excuse for using meaningless variable/method names or allowing a badly thought-out feature of the language (I’m talking about you, blocks-as-parameters) to keep you from explaining what you’re doing. You’re not necessarily writing comments to explain it to the next guy; the next guy could be future-you.

  3. Everyone knows undocumented code is bad. Self documenting code is merely pretentious undocumented code.

  4. No code is self-documenting no matter how well it is written, descriptive names are chosen, etc. Thinking code is self-documenting is a myth.

    There are 2 good reasons to document your code – for yourself and for whomever maintains your code. If you haven’t looked at your code for a few months, when you go to add a new feature or fix a bug, you will look at your code and wonder “I wrote this code?” Without documentation you will spend lots of time getting your mindset back to where it was when you wrote the code. What you thought was self-documenting isn’t when looked at anew.

  5. A software engineer should ask themselves “Do my comments express something that could expressed equally well through code? If so, are my comments a crutch for poorly structured code?”

    For me, the goal of “self documenting code” isn’t really to eliminate documentation, but to make sure the code itself is as expressive as it can be.

Leave a Reply

Your email address will not be published. Required fields are marked *

To create code blocks or other preformatted text, indent by four spaces:

    This will be displayed in a monospaced font. The first four 
    spaces will be stripped off, but all other whitespace
    will be preserved.
    
    Markdown is turned off in code blocks:
     [This is not a link](http://example.com)

To create not a block, but an inline code span, use backticks:

Here is some inline `code`.

For more help see http://daringfireball.net/projects/markdown/syntax

This site uses Akismet to reduce spam. Learn how your comment data is processed.