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
jfruh
Apple syncing patent can't come soon enough
pasmith
New Twitter features borrow from 3rd party clients
Esther Schindler
Open Source Changes the Software Acquisition Process
mikelgan
How to set up continuous podcast play on the new iTunes
David Strom
Five important Windows 7 mobility features
sjvn
Guard your Wi-Fi for your own sake
Sandra Henry-Stocker
Grepping on Whole Words
Sidekick: The Good News & the Bad News
Either way you look at it Microsoft Data Center management did not follow standards or best practices in this failure. In which case it makes me wonder more about the outsourcing of corporate data much less personal data.
- mburton325
Join the conversation here
Quick, practical advice for IT pros. Made fresh daily.
Want to cash in on your IT savvy? Send your tip to tips@itworld.com. If we post it, we'll send you a $25 Amazon e-gift card.













