C. Keith Ray

C. Keith Ray is developing software for Sizeography and Upstart Technology. He writes code for multiple platforms and languages, including iOS® and Macintosh®.
Go to Sizeography and Upstart Technology to join our mailing lists and see more about our products. Keith's Résumé (pdf)

Monday, April 6, 2015

Tesugen.com on Documentation

(Originally posted 2003.Jul.04 Fri; links may have expired.)

Peter Lindberg wrote:
The assumption that lies behind the question You have documented this, haven't you? is that code is inherently unreadable and that there must be a manual to explain it. Many projects indeed are like that. Many projects have grand vapor architectures that exists only in the minds of those who have devised them, and can't be found anywhere in the code. Any document in such a case only reflects the vapor architecture, and is of little help to understanding the code. Let's hope there are still survivors to answer your questions.
My goal donor asked me, You have documented this, haven't you? to which I replied, No, except for the 570 or so automated test cases Malte and I have written during the course of the project. Each test case captures a micro-scenario in the life of the system, by setting up the objects involved, telling them to do something together, and verifying the outcome. And the fact that they are executable means that a programmer new to a team, besides having an explanation of the code to read, written in code itself, can execute that codee to see if the system still works. So it's better than documentation.

No comments:

Post a Comment