FAST Forth Native-Language Embedded Computers

Listing Eight-a. Maximum-stack-depth version-hard to understand or add comments.
: SETLCDADR ( n -- )
F AND DUP 7
> IF 7 AND 40
OR THEN 80
OR LCDINSTR! ;
Listing Eight-b. Sentence-line version.
: SETLCDADR ( n -- ) ( n IS CHR POSITION #, RANGE O-F. 1
F AND ( LIMIT LCD ADR TO 00-OF FOR 16 CHR. )
DUP 7 > ( SEE IF CHR ADDR IS FOR 2ND $ OF DISP . )
IF 7 AND 40 OR THEN ( IF SO, CLR BIT 3 & SET BIT 6. 1
80 OR ( SET BIT 7 TO INDICATE LCD CHR ADR.
LCDINSTR ! ( GIVE ADR AS INSTRUCTION TO LCD.
Listing Nine.
: LCDDATA! ( C -- ) ( LCD DATA STORE. 1
RIOTDRA C! ( SET UP DATA LNS ON LCD. 1
LCDDATAWR RIOTDRB C! ( SET UP R/W & RS ON LCD. 1
LCDDATAWRtE RIOTDRB C! ( SET LCD ENABL LN TRUE SO LCD TAKES BYT. )
LCDDATAWR RIOTDRB C! ( SET LCD ENABL LN FALSE AGN TO END WR CY.)
LCDNOWR RIOTDRB C! ; ( SET R/W LN BK TO RD. )
In spite of this, sometimes it is still practical to make an
English sentence. For example, you can have
TURN OFF "TEST" LED
where TURN is a variable, OFF is a standard Forth word
that zeroes the cell at the address shown by the number
at the top of the stack, "TEST" is a constant with a one
in the bit corresponding to the light-emitting diode (LED)
labeled "TEST" on the front panel, and LED is a colon
definition that examines TURN to know whether to turn
the specified light off or on. There is no question left as to
what this does.
Line Breaks
A common problem contributing to unreadability is
that of poor word arrangement on lines. Prose would be
very awkward done this way:
The manager called Betty.
He asked her to come into his office.
The manager dictated a letter.
Betty took the dictation.
Betty typed up the letter.
but this is perfect for programming! Violations will often
be accompanied by very inadequate commenting, since it
is harder to get a comment sentence to match up with a
line of code that does not resemble a sentence. It is ironic
that explanation is needed most when it's hardest to fit in.
I wish I could include some examples of code I've seen
where these principles were severely violated but, if I did,
someone would probably be very unhappy. So I just tried
to come up with some artificial examples.
Listing Eight shows a definition used to tell a one-line,
sixteen-character, liquid-crystal display (LCD) where to
put the next character it receives. First look at the
"sentence-line violation" version in Eight-a.
It becomes much more readable when we use the line
breaks to divide program "sentences." This also makes it
easier to match some good comments to each line, which
in turn further improves human comprehension. Look at
Eight-b.
LCDDATA! in Listing Nine is an example of the
program sentence-line concept, coupled with vertical
alignment that improves our mental "factoring." This word
was used to store a data character (as opposed to an
instruction byte) to the same LCD. The RIOT (RAM,
11'0, and timer) was an IC on a board I was working with.
DRA and DRB are its data registers A and B. The words in
the left column are constants.
There is nothing left on the stack at the end of any of
the lines in LCDDATA ! in Listing Nine. This brings us to
another point that ties in with the sentence-line concept.
Zero-Stack-Effect Lines
Code is much easier to understand if we minimize each
line's net stack effect as well as the final stack depth. This
is closely related to the sentence-line concept, in that we
want to tie up loose ends as much as possible before
finishing the line. More often than not, it is impossible to
Forth Dimensions 25 March 1994 April