“the source code is the ultimate documentation”

The BBC reports (here too) that Microsoft is to allow access to the source code to selected products. This interesting move will hopefully satisfy the competition commission who are pushing Microsoft to provide more documentation for their products such that vendors can make their own products more compatible. So, rather than provide written textual documentation, Microsoft are saying that their code is their documentation. That’s true enough, gone are the days when developers had to maintain what amounts to two sets of documentation: the code and the written documentation that went with the code. With customers crying out for updates and bug fixes, it’s not difficult to guess which activity is ignored…updating the documentation.

Even comparatively recent, with the divergence of the code and the textual documentation, along came many attempts to integrate the documentation into the code, which is fine, just so long as it’s possible to “hide” the integrated help as it frequently gets in the way during the development process. I have to admit to disliking the bulk of automated documentation that I’ve seen so far: it’s either very much incomplete or there isn’t enough of it – a single line of documentation for a method isn’t really enough. So it’s for this reason that I prefer to treat the code as the best way of gaining an understanding of how something really does work. Remember that documentation goes out of date, folks don’t update it as frequently as they update the source code, the only surefire way of guaranteeing that you’re about to do the right thing, is to look at the source code.

Microsoft’s legal chief, Brad Smith goes as far as saying

the source code is the ultimate documentation…It should have the answer to any questions that remain

However, Neelie Kroes, the competition commissioner disagreed:

“Normally speaking, the source code is not the ultimate documentation of anything…”

“[This is] precisely the reason why programmers are required to provide comprehensive documentation to go along with their source code.”

I’m afraid to say that I disagree with Neelie’s last statement. If I was building a product, whether it is software or hardware, and I was integrating it with a Microsoft product (or any software vendor for that matter), I would be happier with the source code rather than a large textual document. Yes, I would like an architectural overview of the system that I’m looking to integrate with, but that need not be more than a few pages and should be graphical in nature. I know that I’m not alone here: how many times have you been working with a product, following the documentation to the letter only to realise (hours later) that the documentation is factually incorrect? We’ve all been there! Frequently, documentation is created by a separate department, with minimal input from the original programmers. Or, the original programmers write the first draft of the documentation, then “the editors” take over an apply their magic…often changing the meaning or interpretation of something critical on the way!

If programmers are required to provide comprehensive documentation, then project managers/customers should allow the programmers sufficient time to create high quality documentation at the outset, and provide them with time to update it. Sadly, in my experience, documentation is one of the things project managers treat as contingency time, or it’s one of the first things that the customer insists is dropped from the project (“you can easily write the documentation later, can we have this extra feature instead?”)

Jack Reeves first raised this idea way back in 1992 when he published works such as What Is Software Design?, What Is Software Design: 13 Years Later and Letter to the Editor. Click here for more information about these essays.

“the source code is the ultimate documentation”, something not missed by this publication that is at least 16 years old:

agile world

Related posts
The code is the design