A Mini-rant on Documentation

If you're releasing a non-trivial API... for example a YAML parser for .NET. Please remember to document the most commonly used functions so it's easy to understand how they relate. Whatever you do, don't write undocumentation.

What is undocumentation? Well, if you didn't follow the link, it's something that looks like documentation but is devoid of anything that makes it useful documentation. Like this:

// Default constructor for the Node object
Node::Node()
{
   // do stuff
}

This documentation says nothing that the code doesn't already say. Writing documentation sucks. I know. But in this case not writing documentation is an equally meaningful alternative. And it saves everyone time. Particularly me since I now know I have to search for code samples or troll message boards and Stack Overflow to get the information I want.

Rant over.

If you insist on taking the time writing documentation make sure whatever you write isn't stuff made obvious in your method signatures. To mangle DC Comics for a second; a constructor is. You don't need to tell me it's a constructor. Tell me what isn't shown in the code. Tell me when I might use it. Tell me how I can cause it to fail. Tell me why I'd need it in the first place. Every piece of your documentation should provide a hint about how you intend your functions to work together. Preferably, these hints should be about as subtle as a pile driver.

Ruby on Rails and the Standard Python Library are both generally good examples of documentation. The parts of Ruby itself that I have used were also generally well documented. For all its faults the parts of the Java library I have used were well documented. The issue there was more the godawful design of what I had to work with.

Programmers are lazy and have a low tolerance for unnecessary work. You know best how your API should be used. You should let your users know what you know. A nice side-effect is, usually, more, and happier, users.

As an aside. The YAML parser I mentioned above otherwise looks good. I might make another, less harsh, post about it earlier. I want to use it. But it's taking longer to grok than I'd like. The result was this rant.