Document As You Go
Even in the middle of the bomb job's 100-hour weeks, I insisted that we maintain our house coding standards and documentation. There are three reasons for this:
- It reduces bugs early on. A rule of thumb indicates that a bug costs three times as much to fix at each release stage after writing. Early documentation of each word/function will reduce your bug level regardless of the programming language. This alone pays for the effort and reduces delivery time. Make sure that you document why as well as what. Your maintenance programmers will thank you.
- Managers like manuals. They may not understand them, but a neatly formatted PDF manual impresses and gives a good indication of programmer mindset and whether this code will be maintainable.
- Especially if your code is safety critical, verification, and validation of some form will be required. Doing it after the code has been written is an awful job.
We use a literate programming system called DocGen. Doxygen and friends are available for many other languages. The cardinal requirement for any such system is that the documentation is never separated from the code. If it is, the documentation and code will become out of step as soon as you enter thrash mode.
A good literate programming system will allow you to generate chapters, sections and simple formatting. If you can include images and generate an index, so much the better. Other facilities that can be useful are a selection of output formats, e.g. PDF and HTML, and conditional generation which allows you to produce different versions for programmers and end-users, or to produce different versions for different operating systems.
Applications
To use a language well, you have to exploit its best features. With an extensible interactive language such as Forth, the interpreter and compiler can be available a runtime. You can use them for configuration scripts, application macros, CGI scripting, SOAP servers, XML parsing and remote debug access. End-users can use the tools too if you provide a set of words tailored to their needs. You can treat Forth as a toolkit for producing application-specific languages. The two examples below come from DOS and Linux systems:
[COM COM2: 38400 baud N,8,1 COM]
which defines how COM2 will be used.
s" /dev/ttyS0 115200 baud 8n1 1 dtr 1 rts DOS" r/w sd0 open-gio ...
which opens a Linux serial port as required for a building management system. The text after the device specification is interpreted by the word open-gio.
In hosted system, we use mini-languages for parsing resource scripts and for defining external shared library interfaces. The following code fragment is a Forth definition.
Extern: BOOL PASCAL PostMessage( HWND hWnd, UINT Msg, WPARAM wParam, LPARAM lParam );
The three previous examples take advantage of Forth's extensibility. The compiler itself is available to Forth programmers, who use it to produce new compilers. The word Extern: above produces both a Forth word and a code generator.
The use of interactivity enables remote debugging across the world. Our PowerNet TCP/IP stack provides a Telnet server. You can access the remote Forth system's text interpreter to find out what is going on. Although we tend to think of this as big system functionality, it's a reality in single chip systems these days. A build of a an open Forth system (interpreter and compiler) with serial and Ethernet drivers, TCP/IP stack, DHCP and multi-threaded web and Telnet servers requires about 116KB of code space and 32KC of RAM (we've also done it with 16KB of RAM). Single-chip 32 bit microcontrollers provide enough code and RAM space.
We needed the interaction when a client's client-placed instruments on a raw Internet feed with no protection at all. The instruments were attacked within four minutes of being connected. After investigation using a Telnet connection from 4000 miles away, we were able to see the symptoms, diagnose the problem and enhance PowerNet's security to pass Linux server tests. The on-board Forth and connectivity saved time and money.
The Candy system is a project control package for the construction industry by Construction Computer Software (CCS); see Figure 4. It is used all over the world for large and small building projects. It planned the Hong Kong airport and metro. Candy consists of about 850,000 lines of Forth source code built on VFX Forth for Windows. The core development team is remarkably small and their productivity is dependent on strong project management using a surgical team approach. The application layer team uses an object oriented approach and notation designed for people who know about construction. Interactive debugging is available in the running application.
Commercial laundries use gravity driven monorails, points (switches in North America) and lifts to move bags of washing around. The control system and panel for one of these is Tracknet, a Forth application by Micross Automation.
What's Next?
In a future article, I describe some of the experimental and bleeding edge Forth systems, including changes to the Forth VM and multi-core stack machines in silicon. You thought your four core box was hard to program -- wait until you have 24 or more cores to deal with.
Acknowledegments
- Construction Computer Software, Cape Town, South Africa
- MicroProcessor Engineering, Southampton, UK
- Micross Automation, Ross-on-Wye, UK
- Richmond Engineering, North Lopham, UK
