FAST Forth Native-Language Embedded Computers

Listing Ten-a. Zero-stack-effect line.
TMBUF ARCTM [ YR MINUTES - I+ ]LIT CMOVE ( Copy time, date to arc buffer.)
Listing Ten-b. A parameter calculated on each line.
CALCULATE SOURCE ADDRESS AT RUN TIME ( comments comments comments )
CALCULATE DESTINATION ADDRESS AT RUN TIME ( comments comments comments )
[ CALCULATE COUNT AT COMPILE TIME ]LIT ( comments comments comments )
CMOVE
Listing Eleven. Comments that need comments.
CODE CODE CODE CODE ( A max addr addr' addr" tok-len)
eliminate all net stack effect; but it is important that we
work toward that goal, nevertheless.
A line with a CMOVE might simply be like Listing Ten-a.
But if it takes a few operations to calculate the parameters,
each of those operations will usually need its own line, as
in Listing Ten-b.
Now (in listing Ten-b) we have a code paragraph made
up of four sentence lines. If this is only part of a colon
definition, a blank line should be used to separate it from
other code that may come above and below it.
Stack-Effect Comments
When code can be written in minimal-stack-effect
lines, there will be little need for stack comments for each
line. Sometimes, however, things will get a bit confusing,
and there may not be any good way to get around it.
If there is any question about what's left on the stack
at the end of a line, that should be cleared up in the
comments. In those cases, I like to start the comment line
with a A as a stack symbol, followed by a description of
what's on the stack after the line is finished executing.
Listing Eleven shows the stack effect comment follow-
ing a line of code in something we bought. It hardly
qualifies as a description. Maximum what? Addresses of
what? Granted, when there are five things on the stack to
tell about, you don't have much room to tell what each one
is. But since that was the case, they should have put a few
lines of "glossary" above or below the code, telling you
that when you come upon "addr," understand that it
means such-and-such. The same would apply at the next
step up, where there is truly a description, but accomplish-
ing it required non-standard abbreviations beyond what is
intuitive.
Dropping down to use another line may initially seem
like an obvious solution to the problem of insufficient
comment room. However, if this requires putting com-
ment space between lines of code that should not be
separated, it may partially defeat the purpose.
Comments
Much has already been said about comments. I will
only add that if there is not enough room to the right of
the code to put in complete comments, by all means-put
a paragraph or two (or whatever it takes) above the code
to describe what it will be doing, and why. No abbrevia-
tions are necessary here. Make a complete description.
Leave nothing hidden! Expose everything! Typing it in
while it is fresh in your mind will take a fraction of the time
it would take to figure it out with inadequate comments a
year or two later when you want to make an update. It will
be even more valuable if someone else has to figure it out.
In some cases, you may need to write about hardware
or other limitations encountered that led up to the decision
to do it the way you did. Sometimes when I didn't do this,
those things have slipped my mind and I would think,
"Hey, there's a much better way to do this!" After spending
some time on it, I would start remembering that I had
already tried my "better" idea and that there was a good
reason for not doing it that way.
Case
Lower-case is generally only for internals, like branch,
lit, litq, etc. For example, in the Forths I've used, DO
compiles do (a different word), and CREATE compiles the
address of the run-time routine called create (also a
different word). The programmer rarely accesses the
internals directly. Because of this, some Forths (LMl's
UR/FORTH, for example) start out by putting the PC in
"Caps Lock."
The ascenders and descenders of lower-case letters are
part of what our brain uses to recognize words quickly
when we read prose, when our eyes stop once for every
few words as we read quickly. Our process of reading
code, however, is much different. When we read prose,
the line divisions are mostly meaningless, existing prima-
rily because an 8.5" x 11" book is much more manageable
than a ribbon a mile long. However, the line breaks in
(Continues onpage 31 .)
March 1994 Aprjl 26 Forth Dimensions