Subject: Re: Good programming practice

The 541 hand crafted tutorial screens plus a couple of thousand data and question screens have been written by 17 different programmers over a space of three years. These programmers came from a variety of backgrounds ranging from first class honours degree in Computer Science plus professional programming experience through to an honours degree in economics with no prior programming experience. This mixture of skills and experience has produced quite a variety of programming approaches even though all the development took place within quite a restrictive set of guidelines.

It has been our experience that it does not matter too much whether your scripts appear up or down the heirarchy in terms of the number of faults introduced to the code or the time taken to fix them. The most important factor seems to be the "natural" aptitude of the programmer; good programmers make things work well under either scheme and bad programmers cock it up regardless! I agree with (I think it was Tim) when he says that this is very much an art.

However, this does not help much in terms of practical advice so here is a list of the most frequent errors/faults which turned up in our reviews (some of these have little to do with the inheritance issue but have a lot to do with reliability and maintainability):

1. Missing "forward"
   • This is the most frequent error by far and has serious implications for the reliability of system book routines. Rigourous code reviews or automated checking of this by a home grown utility seems to be the only way to avoid this common but serious error.

2. Inappropriate positioning of "forward"
   • Until programmers really got to grips with what happens further up the tree when you "forward", they found it extremely difficult to decide where to place the forward in handlers. Corruption of sysLockScreen was the most common side effect of this.

3. Inappropriate use of "break to system"
   • Breaking to system is a fairly violent command and can really upset your handlers up the heirarchy if you have them. It affects those below too - as far as they are concerned, they just did a "forward" and it never came back.

4. Leaving sysSuspend=false
   • Turning off error reporting is a really useful feature of ToolBook and can save loads of round the houses coding. However, it is not uncommon for programmers to mistype the "sysSuspend=true" (eg. sysSyspend=true) or to do something careless like a "return" or "break" before the line which resets the sysSuspend.

5. Missing "system" variable declarations
   • ToolBook does not report an error if you access a global (ie. system) variable without declaring it in a handler - instead it kindly(!) declares a local one for you.

On the subject of widgets and system books, I have made use of both approaches and I see the pros and cons as follows:

A. Self contained: all scripting on widget

• Highest degree of reusability, particularly if reuser is a novice programmer.
• Wasteful of system resources and requires update utility to do version control on the multiple copies of the widget.

B. System book (or book script) level: little or no coding on widget

• Most efficient in terms of resource and error correction.
• Difficult to reuse individual components without further programming. Things tend to get weaved together and, in keeping with traditional "good style" depend on scattered subroutines.

C. Hybrid: widgets take system books and resources with them when pasted

• Best of both worlds but difficult to implement and difficult for someone else to understand how the thing works. Requires you to make a lot of assumptions about how other people's system books behave.

I reserve final judgement until I have looked at the reliability metrics of the two versions of our development tools: the in-house production, system book based version; and the public release QuickStart self contained widgets version.

Cheers
Simon

----------------------------------------------------------------------
Simon Price                                      Direct: 0117-928-8462
TLTP Economics Consortium                        Office: 0117-928-8478
Centre for Computing in Economics                Home  : 01643-862-320
University of Bristol                            Fax   : 0117-928-8577
8 Woodland Road
Bristol  BS8 1TN                      Email: Simon.Price@bristol.ac.uk United Kingdom
----------------------------------------------------------------------