The Good, the Bad, and the Ugly (Documentation)

Documenting, once a constant in the world of software development has become, with the rising of Agile Development, a somewhat controversial subject. As late as the mid 90's it was a well known fact that you have to document. The more documentation, the better. Management expects it to be there for posterity! Documentation is all that enabled a corporation to retain its intellectual property once the developer of a software project left the company. The larger the company, the more regimented the documentation was to be. There'd be page-long paragraphs at the beginning of each file, describing who wrote what, copyright, purposes, and examples and so on. Then you'd have a few lines above every method, procedure or function, describing its purpose, and usage. Then each block of code (roughly 5-20 lines) would be documented as well.
And that is without mentioning the Book. The book is a thick manual describing the system, "ideally" capable of telling the would-be programmer everything he needs to know about how to develop.

Of course, I haven't, in my 15 years of development, occasionally modifying code that was up to a decade old when I reached it, seen documentation worth reading. It was consistently outdated, in variable degrees of staleness. What was there was often self evident, once I understood the codebase. Needless to say, it was of limited use to me.
Reflecting back on the matter, I wonder if this uselessness could be the reason for the neglect by myself and others before me.

Then came Agile (bring out the fanfare). A new world order was emerging into existence. YAGNI and TAGRI came marching in, bringing down the hegemony of farsighted API and vast documentation (respectively). A new concept became publicly known: quality of documentation. What should you document?

The hardest part of writing this post was to define the difference between bad documentation and ugly documentation. In the end, I came up with it. So, without further ado, here they are:

The Bad

Bad documentation is a comment, that is, quite simply, not worth reading. Reading bad documentation is at best a waste of time, telling you nothing worth knowing, or something that is self evident. At worst, bad documentation is misleading, and reading it will lead to false assumptions and mistakes. Here are a few examples of bad documentation:

• Not worth knowing:

// I can't remember what this function does
bool DoSomeObscureOperation(object a, object b) { ...}

You may laugh, but I've seen this. Many times. This kind of documentation earned many a developer in my team a spanking. Well, I didn't actually give one, but I really wanted to. If you aren't explaining the code, don't do it there. Don't write about not remembering something - ask someone.

Note however, that many IDEs allow for placing to-dos and tasks in the code as comments. These are useful place holders to let a developer record what must be done, but couldn't for some reason.

• Self evident:
  // Returns the list of the user's favorite titles
  List<Title> GetUserFavorites(User user) { ...}

No, Really?!? I swear, I saw this. I admit, as a developer, I once was required to write such comments. I never understood why, and I discourage such bloat in my codebase.

• Misleading:
  // Returns the list of the user's favorite titles
  List<Actor> GetUserFavorites(User user) { ...}

Obviously, either this comment is the victim of a Copy-Paste gone badly, or the new operation was added between the comment and the original code. This might seem contrived, but see what happens when you get run time errors, because you used the wrong operation, based on the code, and then typecast the result to a different kind of collection.

Bad documentation can also be more insidious. It can disguise itself as good documentation, describing bad code. If you have bad code, don't explain it - fix it! It should be easy after all. You've got your Unit Tests in place, right?

The Ugly

Ugly documentation stacks with bad documentation (i.e. it makes bad documentation worse). It can also disguise good documentation as bad. Ugly documentation is simply hard to look at. It can be full of spelling mistakes, its indentation can be off, capitalized, all in one case, etc. If it offends your eye, and you'd rather ignore it, it's ugly. Perhaps a spell checker wouldn't go amiss here.

The Good

Good documentation is easy to spot, easy to describe, and a real challenge to write. It is everything that bad and ugly documentation isn't: It's well written, it tells you something you didn't know, it's synchronized with the code, it reduces effort and it saves you from making mistakes. The challenge, in writing good code, is knowing when to comment, and when to refactor. Good code is self documenting. The best documentation is the code itself: It never lies, and it isn't self evident (in as much as without the code, there would be nothing).

This is what I ask my team to document:

• For each class and interface, describe shortly what its (single) responsibility is. This helps other developers to decide where they should add that new operation they need, as well as what they need to use.
• For service APIs (only), document the service contract as you would a class or an interface. Additionally document each operation - as long as you aren't translating the operation signature into English.
• Avoid in-method comments. Make the code self evident. Use good variable and method names.
• As a last resort, if you really can't refactor a hard-to-understand operation, explain the purpose of the algorithm (not the algorithm itself). But for your team's sake, make sure it is the last resort. Code changes, so you'd be better served documenting the abstract and using member-names for documentation.

There. That's it. Now you know. And finally, a piece of parting advice:

If you're gonna code, code. Don't doc!

Yes, I was rather proud of that one.