FAST Forth Native-Language Embedded Computers

Garth Wilson
Whittier, California
I had been thinking about writing an article on read-
ability of Forth code, but I became more determined after
going through a recent issue of Forth Dimensions. It was
full of things that reduce code readability, cover to cover.
It's no wonder some have called Forth a write-only
language! It doesn't need to be this way. If a programmer
gets the application working but the code is unreadable,
he hasn't done his job.
After looking through my library at others' treatments
of the subject, a part I see as lacking special attention is
what Jack Ganssle calls "pretty code."' It has not been
stressed enough in our programming industry. I've had
non-programming superiors who thought that any work
beyond "just getting it working" was frivolous, and that the
programmer who spent the time was not sensitive to the
company's needs.
Jack Ganssle tells of a Volkswagen Beetle maintenance
book he had which strongly encouraged the owner to
keep the engine clean. One reason was that you're more
likely to keep it in good shape if you can do the necessary
Producing readable code
is not an objective procedure
with an exact formula.
maintenance without getting filthy. We've all seen a lot of
"filthy engines" in our industry-ones we don't want to
touch.
I've had code that was sold as "toolbox" code that was
too unreadable to figure out what was necessary in order
to use a small piece of it in my own application. I thought,
"Why'd they even bother?" It doesn't have to be that way.
Special attention will be given here to layout, and to
making the layout more perceptible. "Layout" here refers
to the decisions as to whatwords will be put on a particular
line of source code, where in the line they will start, use
of blank lines to separate code "paragraphs," where the
comments will go, etc. Let's look first at vertical alignment,
then line breaks, zero-stack-effect lines, comments (in-
cluding stack-effect), and case.
* "The C Blues," Embedded Systems Programming, April 1993
March 1994 April
Vertical Alignment
Comprehension is accelerated dramatically by vertical
alignment of related elements. Structure words need to be
aligned vertically unless the structure is very simple; for
example, BEGIN ?TERMINAL UNTIL would fit nicely on
a single, very readable line; but ?DO and LOOP in Listing
One need to be one above the other, obviously standing
out from the contents of the loop.
The indentation should be at least three spaces. Re-
cently I was trying to read some code in a book. The
indentation for setting off loops was only one space,
which made it look like the printhead just didn't come
back to the same place with every carriage return, produc-
ing a ragged margin.
Having many nested structures can be a pain, and can
usually be avoided by making each nested level a separate
definition. In some cases, however, it is difficult to come up
with a truly descriptive colon-definition name that's any
shorter than the code itself. Having neither good names nor
the code right there, you will have trouble understanding
the flow of what the code is supposed to do. Vertical
alignment and readability can still be preserved using
methods like the one shown in Listing Two-a instead of
Listing Two-b.
Listing Two-b is far more confusing, and takes just as
many lines, despite the lack of blank lines to set off the
different parts. I've seen this kind of thing carried to the
extreme, making a huge sideways 'V' from the top of the
printed page to the bottom, with the point of the 'V'
indented so far over to the right that it left no room for
comments.
Many Forth programmers would say a definition should
never get this long, and would proceed to "flesh it out" in
Forth one-liners, requiring many, many levels of nesting
at execution time. I would go along with this only as long
as the colon-definition names are very descriptive of what
they do, and that the "fleshing out" is not used as a
substitute for good commenting or layout.
Vertical alignment of similar words on lines helps, too.
Our brain homes in on patterns that simplify the mental
processing and memory requirements of the material.
Consider Listing Three-a. These simple definitions can be
I Forth Dirnensior