Reading Code is Good, Writing Documentation is Better

2010-10-15

Yesterday, John Nunemaker wrote a widely disseminated blog post on reading code. He argues that instead of searching Google or asking a mailing list when trying to figure out how to use a software library, developers should open up its codebase and just start reading. John is 100% right. In fact, I too once opened up the Typhoeus library to figure out which options were available to me. Having a high level of code literacy – when it’s not your code – is essential to our craft.

But considering that point alone ignores what should be an important social contract when it comes to libraries. Software libraries, whether they be called gems or packages or jars, are a unique kind of software: their users are software developers, not actual end-users.

And we software developers are busy. We have work to do. We hate wasting time (when we don’t choose to, that is). If I have to open up your codebase while working with your software library, then something went wrong while using your software library.

As a library author, you should not expect your users to read your code to understand how to use your code. Instead, you should write thorough and clear documentation. A single blog post isn’t enough, and neither is relying on sparsely written inline documentation.

In this age of GitHub, your library should be fully documented in a README. Tom Preston-Werner advocates for Readme Driven Development: write your Readme first, before a single line of code. Every object, method, and parameter that is meant to be available to the users of your library needs to be described. Critically, there should be no ambiguity. If you’re writing inline documentation, feel free to repeat most of it in the Readme. If you practice test-driven development, you can usually copy and paste bits of your test cases into your Readme.

Beyond the Readme, consider setting up a dedicated website. If your library is sufficiently complex, breaking the documentation down into distinct sections and pages may make more sense. Some projects that practice this are Mongoid, DataMapper, and of course, Rails. Though they’re technically command-line tools, both Bundler and RVM have terrific documentation too. Yehuda Katz likes to keep a completely separate repository from the codebase for a documentation site.

Reading code is sometimes necessary. Maybe a bug or error has occurred, and the stack trace tells you it’s happening from inside the library you’re using. There are at least two possible causes here. You may not be using the library correctly, or there may be an actual bug with the library. Good documentation, along with helpful error messages, would help you avoid the first case. The second case–a genuine bug–is actually the more forgivable mistake by the library author. One never intends to introduce bugs, but one does make the decision to not write documentation.

To be clear: reading code is an important skill to have. Developers should not be afraid to do it. But if I were asked to choose between two programmers, one who writes good documentation but is awful at reading other people’s code, and another who never writes documentation but is great at reading code, I would favor the first programmer. Being able to read code is good, but writing documentation is better.