Most of the time, I don’t like talking about documentation. I particularly don’t like talking about documenting code. There’s not much to say.
I do like talking about testing though, since I enjoy writing code TDD, since tests forbig, big, big programs are really hard and because most everyone else is doing it wrong.
Thing is, every time I talk about testing in the Python world, I have to talk about documentation because someone always brings up doctest and thinks it’s a good way of testing code. It’s not. Andrew has explained clearly the problems with the principle and with the implementation. He concludes that the only thing that doctest is any good for is writing self-testing documentation about Python code, and I agree.
However, I humbly suggest that for many projects, this is a solution in search of a problem. Which means I am going to have to talk about documenting code. Before that, a short plea.
Please stop talking about documentation and testing at the same time! They are both actually quite tricky, and you can never, ever, ever effectively address both of them with the same initiative. They are different! Just stop it!
OK, let’s talk about documenting code.
Before you even begin to talk about the best way to document your code, you must seriously consider why you are even bothering.
Time spent documenting code is time not spent fixing bugs. Instead of writing docs you could be talking to users, making your software internationalizable, improving its website, improving the user documentation, making the test suite run faster or any number of things that directly help your end users or your existing developers.
You might want to document your code as part of an initiative to get more contributors, or to make your existing contributors’ lives happier. If so, great, but make sure that documenting code will actually achieve these goals.
If not, take pride in your lack of code documentation! It is the direct fruit of you doing better things with your life. Stand up, walk out the door and skip down the street, clutch the first suit-wearing stranger you see by his lapels and shout “My code is under-documented, yippee ki-yay!”
More seriously, know why you are documenting your code, don’t just do it out of guilt, and don’t feel guilty if your code is under-documented while your users are many and happy.
Audience and benefit
Do not even bother to write a document unless you have an audience in mind and a clear benefit in mind for what they’ll get out of reading this document. And no, “help them understand the branch puller XML-RPC API” is not a clear benefit.
As an example, I’m writing this blog post primarily for Python programmers at work and in the open source projects I care about. My aim is to convince them to be silent about doctest when we’re talking about testing and to see the whole picture when talking about documentation so that they’ll have good unit tests and won’t misdirect energy toward inappropriate documentation. I have a secondary aim of learning where I’m wrong by reading the comments.
If someone is reading documentation that’s about code, then they can probably read code. You can probably save everyone a lot of trouble by picking better names, adding a couple of docstrings, fixing the bits you’re embarrassed by and deleting the crap that you don’t need.
To put it another way, when people say “this needs documentation” they often mean “I don’t understand this” (similarly, “we have a communication problem” often means “you are not doing what I want”). The best way to help them is not necessarily to write documentation.
Value is in the output
Documentation that’s not being read is worthless and probably incorrect, much like code that is not being executed. Documentation that cannot be found cannot be read. How is your audience going to find your documentation? Is it going to be in a format they like to read? Don’t bother writing anything until you’ve figured this out.
No documentation, just code
Some people believe that no human language text should ever sully their code base. There are plenty of good sentiments behind this idea: source code is a powerful tool for describing how to think about a problem; textual documentation about code frequently goes out of date and it’s often used as a crutch for bad code.
Personally, I think it’s a bad idea to have no documentation. Even the best coders read good prose faster than good code, and text has a wonderful power of summary that code lacks. Sometimes it’s impossible to communicate the intent of the code in the code itself (for example, you might be working around a POSIX insanity). Nothing wrong with using a crutch when your leg is broken.
API reference documentation
Instead of having no documentation, you can use Python’s docstring
feature to add a mini-document describing a class or function. This
docstring can tell you how to use it, what to expect from it, and most
importantly, why you should care. Because Python functions don’t have
explicit type declarations, these docstrings can be very useful (is
branch parameter a Bazaar branch, a Launchpad
IBranch object or
the URL for a branch?). Also, because the docstring is so close to the
code, they are much less likely to be out of date or incorrect.
Some people like having specifications as part of the documentation for their code. I haven’t really seen this in practice, so I can’t comment much. I can say that I find good comments on unit tests extremely helpful, and now almost always write such a comment before I write the test.
Guides, tutorials and howtos
Rather than consulting a reference, you sometimes want to be guided through a task or to be introduced to some new area of the problem domain. In these cases, it’s pretty hard to beat a solid chunk of prose with some code examples. It’s here that doctest shines, since it’s quick to write, can be rendered nicely and can be executed to guarantee the code is not hopelessly wrong.
Code documentation is not intrinsically valuable. It has no value unless you give careful thought to why you want to do it and how it is going to connect you to your audience. Once you’ve done that, prose documentation can be very helpful, but you can also get a lot of the same benefits by cleaning up your code base.
Doctest is neither necessary nor sufficient for good code documentation. Do not use it simply because it is there. Use it when it fits.
Now, please can we go back to talking about testing?