Use the tests, Luke!

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.

Sign up for ITworld's Daily newsletter
Follow ITworld on Twitter @IT_world

• Email
• Print
• Share
  • Slashdot
  • Digg
  • Stumble
  • Reddit
  • Newsvine