April 11, 2005, 10:07 AM — There is a myth prevalent in some circles that technical folk, particularly programmers cannot write. This myth is used to explain why so much documentation of computer code written by programmers is so bone-crunchingly awful.
Programmers, in my experience, can write reasonably well. You can see many examples on the Internet these days. On Usenet groups, on mailing lists, on weblogs, there are many fine programmers producing readable, useful words. These guys can write just fine.
Closer to the truth is that programmers only write well when they are fully engaged and passionate about something. That tends to be the case in their Internet emissions and tends not to be the case when they are writing documentation for their code. Why? Because programmers prefer to write code.
That is only part of the story though. Imagine that you have totally lucked-out and your development team has produced great documentation for your system. Your system will change over time. We use the euphemism 'maintenance' to refer to this process. Maintaining 'old' code is not something programmers like to do if they can avoid it. However, maintaining 'old' documentation so that it stays in sync with the code as it changes, ugh! They would rather get that overdue root canal work done than do that for a living.
Now this problem is not a new one. I believe it was Donald Knuth who invented the term 'literate programming'[1] to refer to one approach to solving it. I won't go into the details here but a capsule summary would be that code and documentation are treated as one and the same thing. They are created at the same time; modified at the same time and kept in the same place.
In a recent Jython[2] project, I had the opportunity to use full-on test driven development techniques. The number of lines of test code for this system significantly outweigh the number of lines of actual code.
An interesting thing has happened in the team working on this project. The code for the tests is being used as documentation for the system. I think about it like this:
1) Test Driven Development is fundamentally good and is the future of
software engineering best practice. Especially in the era of
dynamic languages that is dawning all around us.
2) Getting programmers to write tests is a lot easier than getting
them to write stand-alone documentation. In fact, with Test Driven
Development, they must write tests. Otherwise the whole system
doesn't work. Good programmers who buy in to the idea of Test
Driven Development also buy into the idea of writing tests. In
fact, the good ones become positively passionate about it.
3) Tests - when done correctly - exercise every nook and cranny of the
system and therefore provide excellent coverage of the
functionality of a system. Test suites do not develop gaps the way
traditional documentation does.
4) Tests must pass! Therefore, tests are always in synch with respect
to the underlying code.
In the early days of Unix, a commonly uttered epithet was 'Use the source, Luke'[3]. This was reference to the fact that the Unix source code was available and thus, if you have a query about how something worked, or found the documentation wanting, you could always read the source code.
Obviously, on my own projects I am in a position to use the source as Luke does. However, I have found that 9 times out of 10, my queries are answered by reading the tests.
Use the tests, Luke!
[1] http://www.literateprogramming.com/
[3] http://www.usenix.org/publications/login/1998-6/luke.html
