Future-Proofing Applications: another purpose of design docs

I was doing some reading recently on statistics and testing, and I came upon a free online book, The Basics of Item Response Theory, by Frank B. Baker. It had originally been published in 1985, with this second edition from 2001. What had made it very popular, it said, was the availability of free, as in beer, software to use while following along with the book. The first edition application was written in AppleBasic for the Apple ][. Fifteen or so years later, the program was ported to Microsoft Visual Basic 5 for Windows 95. I don't know if the program runs on modern Windows computers. It certainly does not work on my PowerPC Mac. I found it unfortunate that a freely available educational program would be limited in this way.

Bouncing these ideas around got me thinking about how it would be possible to future-proof an application. It is clear to anyone who has worked at a large company more than 20 years old that aged software platforms are a real problem. Internally developed applications become a mainstay of business operations, but more and more quickly, it seems, the computers and operating systems to run these programs become obsolete. Companies in the situation of upgrading their computer systems can use one of several strategies. Most common, perhaps, is to port the app to a new platform. This usually involves a large expenditure in software development and user retraining and many headaches as new systems attempt to replace the old while having the kinks worked out of them. Many resist porting and end up keeping legacy systems in place long past their expected life cycle. Another possibility is to upgrade computers but keep legacy applications alive through emulation software, which can have a slew of problems of its own.

It is a fact of modern life that programming languages, operating systems, even user interface devices change over time. To truly archive the functionality of an application would require isolation from all of these factors. One such means which would work for simple applications at least, occurred to me. Basically, the idea is to record the functionality of the program in an easily read and understood design document.

To illustrate, I will create a description for a game of tic-tac-toe as a dialog between the user and the computer. This technique is similar to a Use Case, but to me is much more clear. The questions the computer asks are the parameters necessary for the program to run. Note that this example is incomplete in that the rules for deciding if the game has ended would have to be specified, but I left this out to keep it short and simple.

• User: I want to play tic-tac-toe.
• Computer: Do you want to be X's or O's, or should I choose?
• U: You choose.
[Assign symbols randomly with an equal chance User is X's or O's.]
• C: You are X's. You go first. Please choose a location for your X.
• U: Middle box.
  
[See if the game has ended. If not, randomly choose one of the remaining plays.] 

• C: I go in the upper left.
  [See if the game has ended. If not, repeat the turns until the game ends.]
• C: You win. Do you want to play again?
• U: No.

The important point of this trivial example is that it describes the functionality of the system while remaining entirely interface-independent. If written for the Apple ][, it would probably use a simple text prompt for user interaction. More modern computers would likely allow the user to click on the game board to mark their move. The choice of X's or O's could be made by a GUI button. The computer of the future might use synthesized speech and voice recognition to interact with the user in a very similar manner to how this dialog is written.

Even the algorithms employed can be written in plain language and left up to the programmer to implement in the most reasonable way for the current architecture. For example, assigning the X's or O's randomly in Java could entail use of java.util.Random class to perhaps check whether the next random integer is even or odd. In Python, the "random" module provides the following easy syntax: human = random.choice(['X', 'O']). As long as the implementation follows the documentation of assigning the marker with equal probabilities, the details are unimportant.

There is another advantage to such documentation. In some cases, especially in the sciences and education, the person creating a computer application is not a professional programmer. However, a domain expert could specify the exact functioning of a desired program and leave the actual implementation to others with more expertise. Even if an implementation is created, the functional specification can be made freely available, allowing others to make versions without needing access to the original source code.

Obviously, the more complex a program is, the longer and more complex its design document will be. Full-blown design languages like UML provide the standardized means to create such documentation. For applications that will be around for a long time, a proper functional specification becomes vital to allow for changes in the computing environment. This is clearly the case with many educational computer programs as well as integral business systems. Well documented design is not just for the initial implementation as most people think it is. It can also be one of the best ways to future-proof applications.