I am not going to start another flame war about whether documentation is evil or not.

My personal stand is that is evil but mostly needed.

One of my biggest concerns with documentation is that, more often than not, tends to become obsolete no matter how hard you try to keep it current. One might seek several explanations, but my personal take is that updating documentation is not nearly as fun as changing code. When I say no matter how hard one try I mean it. I do not intend to disregards completely the value of documentation altogether, but I intend to point out just another example that supports by beliefs.

Busted!

How much do you think Microsoft spends on documentation? Well, they do have technical writers and correctors and probably proof-readers of corrections, so I would assume they spend more than the average software company does. Some people believe they are not in the bottom half of the table when it comes to documenting their software. At least I think the BCL documentation is not horrendous, although it has its WTF highlights.
And this praise would be all I’d to say if software was static, but, alas, it is not. Methods evolve, and internal changes sneak in unnoticed.

One of such changes is exceptions thrown by a method. .NET does not, fortunately I would say, have the concept of checked exceptions, in which the exceptions thrown by a method become a part of its signature. .Net has the concept of documenting the exceptions, but there is no compiler activity in checking whether the exception can actually be thrown in the execution path of the method. so one might happily add or remove exceptions inside a method and the compiler would silently do its job with no complaints.

That exact event happened to a pretty popular .NET class, the Thread. In version 4, a check was removed for the setter of the CurrentCulture property. In previous versions one could not set the current culture of the thread to a neutral culture or a NotSupportedException would be thrown.

Of course documentation was never updated to reflect that change in code.

How did you?

It happens that Testing.Commons contains a class that allows having fine control over the culture a piece of code (mostly a test) runs. Its name is CultureReseter. A variant of such class has been used for some time now in software running previous versions of the framework.

Such class had zero lines of documentation. Instead it came with a bunch of unit tests that told you how to use it and, most importantly, how not to use it. In one of such scenarios the potential user of my class was pointed out that a neutral culture is not valid when setting the current culture of the thread, as doing so would throw an exception.

Of course when I tried to run a similar test on .NET4 (the platform of choice of Testing.Commons), it automatically failed. I was puzzled. At first I double and tripled checked what I was doing wrong as I thought that such behavior had not changed. Hell! the documentation was telling me it had not changed!!! I had to fire my {decompiler-of-choice} to see with my own eyes that the change, indeed, happened and that my test was catching the change of behavior.

So?

Does that mean we should ditch documentation at all? Nop.
But what we could do is use documentation for things that cannot be expressed in code. And let code, in the shape of test, speak about the behavior of each class.

No offense for technical writers, but we would be better off with less of those and more developers engaged in the endeavor of writing good, expressive tests as a mean of documenting behavior and making it available for us developers.

There is no better documentation.