This implementation deviates from the original specification in a number of ways:
• the number of entries is not defined,
• the display format is slightly different,
• changed extension numbers are not removed.
In effect, the implementation is a quick and dirty hack to get something running. However, it raises several issues about the specification:
• Why are names restricted in size?
• How should the phone book be saved?
• Can two people have the same name?
• Do people share extensions?
In my career it has been very rare to receive a complete or good specification. In practice specifications evolve by refinement – the “spiral lifecycle” rather than the “waterfall” model. However, an implementation architecture that makes a false assumption about the long-term evolution of the system will eventually fail and have to be discarded. Fixing architectural faults is often more expensive than starting again.
Using the Forth interpreter
When you are faced with a new specification, you have to question it. There are often assumptions made by the authors about software that are invalid. Similarly, as a software engineer, you are likely to make assumptions about the application that are also invalid. The fine (and often critical) details about the process being automated are all too often unstated in the specification.
Another crucial part of the initial stages is to simplify as much as possible. Separate the main objectives from the “wouldn’t it be nice ifs” (WIBNIs). In the later stages of a project WIBNIs often introduce complexity, consume more time than the original objectives, and delay product launch. Although the marketing department and salesmen are key friends early on, their enthusiasm can generate unexpected problems later on. In most projects, and especially embedded ones, the software people are the last in the chain, and thus are most visible for late delivery, even if late delivery of out-of- specification mechanical systems is the cause of your grief. On one project I worked on, the mechanics were taken away for overnight painting and were delivered back four days later, leaving less than eight hours for software testing before the system was delivered for trials.
Analysis of large software projects shows that frequent deliveries of software modules that can be tested contributes enourmously to project success rate. If the architecture is right, additional features can be added later. Giving the end-user something to try contributes to the sense of progress and reveals any design problems early. Fixing something costs as at least three times as much as getting it right first time.
One of the key benefits of Forth is that the interactivity allows for very rapid investigation of faults. You can use the interactivity not only for debugging but also to demonstrate possibilities to people in other disciplines. In order to do this successfully you have to have an initial chassis to work from. So deliver something early and use it to test not only software, but also the specifications and assumptions you are working from – not only other peoples’ assumptions, but also your own.
Code Layout
18
Code Layout
Code layout is a vexed topic in any programming language. Many programmers, especially “guru” class programmers, have a style of their own and are reluctant to change it. However, from my own observation of large projects, the use of a “house style” for source code produces significant benefits over the lifetime of a product. The larger the team, the more important this becomes.
This does not mean to say that a house coding style should not evolve. My own programming style has changed as I have learnt, and in some cases it changes it according to the application domain and who is going to read the code.
The key features for a source coding standard are
• Consistency from one programmer
• Consistency between many programmers
• The standard is easy to follow and understand
• The resulting code is easy to follow and understand
• Code which is difficult to get wrong because of layout
• A layout which is also visually pleasant
A secondary (and increasingly important) benefit is that a consistent style makes it much easier to use automated source maintenance and documentation tools. This may not appear worth much for a quick and dirty project, but it is invaluable for large projects. There are current Forth projects approaching 1,000,000 lines of Forth source code. A description of the requirement of the standard will be followed by an example. In the example, the relevant code fragments will be printed in UPPER CASE. The comments in the example will be in lower case. However, the case of the characters used in real code is not specified. Some compilers may be case-sensitive, others not. Also different programmers may have case preferences. The code examples in this document will assume that the left-hand end of the line comes directly below the left-hand end of this type of text. Indented code will be relative to this column position:
\ the beginning of the line \ indented by one space
Why a standard?
There are several reasons for producing and following a standard for anything. This standard is produced for the following reasons.
In any organisation, if many programmers are all using the same language, they will inevitably be sharing source code, or working in teams on a given project. If every programmer writes code to his own or no standard, then communication will be difficult, and programmers will tend to prefer to re-invent the wheel rather than try to
Code Layout
understand and use another person’s code. This is both costly and time-consuming. By following a standard - any standard - each programmer’s code will be meaningful to the others.
When a programmer starts to learn a language, he or she will not know how best to either write or lay out the code being written. Tutorials abound to teach the syntax, structure and word-set of Forth, but there is little advice given on layout and practice. This document seeks to offer the collected experience of staff at MPE so that other programmers learn an accepted and clear standard.
However, the standard as presented here should not be taken as a diktat. If an organisation has its own specific layout or documentation requirements, these should not be ignored. A standard is there to help, not hinder in the production of source code. Other Forth coding standards exist. A good place to start looking for them is at
http://www.forth.org.