Use the source wisely, Luke

No matter what the documentation says, the source code is the ultimate truth, the best and most definitive and up-to-date documentation you're likely to find. Sounds really good. But grand sentences often sound really good — better than reality even. So let's try checking that against the concrete code and documentation I personally have written. Have I written anything where the documentation describes the code better than the code itself does?

Here's what I could think of during the time it took to brew myself a pot of tea:

I have written code that was not supposed to be used, except by internal unit tests. For instance to get January 1, 1970 instead of the current time. Very useful for unit tests, but do you really want to depend on that kind of thing?

I have written documentation that described only what's common to the current and the the next major version (in Qt, I did that many, many times). Anyone who depended on the documented behaviour got a simple upgrade, anyone who read the source might get trouble, often the trickiest kind of trouble. I remember people who read the Qt source, learned too much about the lifetimes of internal objects, and then the the next major version deleted those objects earlier.

I have written documentation that intentionally misled the users so as to steer them away from trouble spots. To achieve foo, do so and so, not mentioning another approach, which would seem more promising at first glance. Again, I did that many times in Qt, when the simpler approach made people stumble and ask support. I'll concede that the source is more complete in this respect, but I would not call it better.

And I've written bug compatibility code. Code meant to keep broken callers from falling over.

In my experience it's best not to document such things. It's easier to write clear and useful documentation if you don't splatter the page with don't do this and don't do that and forget the previous paragraph, we've made a better API now, namely ….

In conclusion, I think that if the source is better documentation than the documentation, then that just means the documentation sucks and so does the maintainer. Film at 11.