chapter5.tex

%% Thinking Forth
%% Copyright (C) 2004 Leo Brodie
%% Initial transcription by Albert van der Horst
%%
%% Chapter: Implementation: Elements of FORTH Style
%%
%% ``%%!!!te'' marks mark typesetting errors in the original
%% We don't want to retain typesetting errors.

\chapter{Implementation: Elements~of \Forth{}~Style}\Chapmark{5}%
\index{I!Implementation|(}%

\initial Badly written \Forth{} has been accused of looking like ``code that
went through a trash compactor.'' It's true, \Forth{} affords more
freedom in the way we write applications.  But that freedom also gives
us a chance to write exquisitely readable and easily maintainable
code, provided we consciously employ the elements of good \Forth{}
style.

In this chapter we'll delve into \Forth{} coding convention
including:

\begin{itemize}%%originally: no bullet points
\item listing organization
\item screen layout, spacing and indentation
\item commenting
\item choosing names
\end{itemize}
I wish I could recommend a list of hard-and-fast conventions for
everyone.  Unfortunately, such a list may be inappropriate in many
situations.  This chapter merges many widely-adopted conventions with
personal preferences, commented with alternate ideas and the reasons
for the preferences.  In other words:
\begin{Code}
: tip  value judgement ;
\end{Code}
I'd especially like to thank \person{Kim Harris},\index{H!Harris, Kim} who
proposed many of the conventions described in this chapter, for his
continuing efforts at unifying divergent views on good \Forth{} style.

\section{Listing Organization}%
\index{L!Listing organization|(}%
\index{I!Implementation!listing organization|(}

A well-organized book has clearly defined chapters, with clearly defined
sections, and a table of contents to help you see the organization at a
glance.  A well-organized book is easy to read.  A badly organized book
makes comprehension more difficult, and makes finding information
later on nearly impossible.

\begin{tfnote}{Bernd Paysan}
This chapter needs to focus more on files than on screens
\end{tfnote}

\wepsfigp{fig5-1}{I still don't see how these programming conventions
enhance readability.}

The necessity for good organization applies to an application listing
as well.  Good organization has three aspects:

\begin{enumerate}\parsep=0pt\itemsep=0pt
\item Decomposition
\item Composition
\item Disk partitioning
\end{enumerate}

\subsection{Decomposition}%
\index{D!Decomposition|(}%
\index{L!Lexicons|(}
As we've already seen, the organization of a listing should follow the
decomposition of the application into lexicons.  Generally these
lexicons should be sequenced in ``uses'' order.  Lexicons being
\emph{used} should precede the lexicons which \emph{use} them.%
\index{L!Lexicons|)}

On a larger scale, elements in a listing should be organized by degree
of complexity, with the most complex variations appearing towards the
end.  It's best to arrange things so that you can leave off the
lattermost screens (i.e., not load them) and still have a
self-sufficient, running application, working properly except for the
lack of the more advanced features.

We discussed the art of decomposition extensively in \Chap{3}.%
\index{D!Decomposition|)}

\subsection{Composition}%
\index{C!Composition|(}%
\index{L!Load screens|(}%

Composition is the putting together of pieces to create a whole.  Good
composition requires as much artistry as good decomposition.

One of \Forth{}'s present conventions is that source code resides in
``screens,'' which are 1K units of mass storage.  (The term ``screen''
refers to a block used specifically for source code.) It's possible in
\Forth{} to chain every screen of code to the next, linking the entire
listing together linearly like a lengthy parchment scroll.  This is
not a useful approach.  Instead:

\begin{tip}
Structure your application listing like a book: hierarchically.
\end{tip}
An application may consist of:

\begin{description}\parsep=0pt\itemsep=0pt
\item[Screens:] the smallest unit of \Forth{} source
\item[Lexicons:]\index{L!Lexicons} one to three screens, enough to
implement a component
\item[Chapters:]\index{C!Chapters} a series of related lexicons, and
\item[Load screens:] analogous to a table of contents, a screen that
loads the chapters in the proper sequence.
\end{description}

%Page 138 in first edition.

\begin{figure*}[tttt]
\caption{Example of an application-load screen.}
\labelfig{fig5-1}
\setcounter{screen}{1}
\begin{Screen}
\ QTF+ Load Screen                                      07/09/83
: release#   ." 2.01" ;
  9 load  \ compiler tools, language primitives
 12 load  \ video primitives
 21 load  \ editor
 39 load  \ line display
 48 load  \ formatter
 69 load  \ boxes
 81 load  \ deferring
 90 load  \ framing
 96 load  \ labels, figures, tables
102 load  \ table of contents generator




\end{Screen}
\end{figure*}%
\index{C!Composition|)}

\subsection{Application-load Screen}%
\index{L!Load screens!application|(}

\Fig{fig5-1} is an example of an application-load screen.  Since it
resides in Screen 1, you can load this entire application by entering
\begin{Code}
1 load
\end{Code}
The individual load commands within this screen load the chapters of
the application.  For instance, Screen 12 is the load screen for the
video primitives chapter.

As a reference tool, the application-load screen tells you where to
find all of the chapters.  For instance, if you want to look at the
routines that do framing, you can see that the section starts at
Screen 90.

Each chapter-load screen in turn, loads all of the screens comprising
the chapter.  We'll study some formats for chapter-load screens shortly.

The primary benefit of this hierarchical scheme is that you can load
any section, or any screen by itself, without having to load the
entire application.  Modularity of the source code is one of the
reasons for \Forth{}'s quick turnaround time for editing, loading, and
testing (necessary for the iterative approach).  Like pages of a book,
each screen can be accessed individually and quickly.  It's a ``random
access'' approach to source-code maintenance.

You can also replace any passage of code with a new, trial version by
simply changing the screen numbers in the load screen.  You don't have to
move large passages of source code around within a file.

In small applications, there may not be such things as chapters.  The
application-load screen will directly load all the lexicons.  In
larger applications, however, the extra level of hierarchy can improve
maintainability.
%Page 139 in first edition.

A screen should either be a load-screen or a code-screen, not a mixture.
Avoid embedding a \forthb{LOAD} or \forthb{THRU} command in the middle of a
screen containing definitions just because you ``need something'' or
because you ``ran out of room.''

\subsection{Skip Commands}%
\index{S!Skip commands}
Two commands make it easy to control what gets loaded in each screen
and what gets ignored.  They are:

\medbreak
\begin{description}
\item[\emph{\forthb{\bs}}]~
\item[\emph{\forthb{\bs S}}] also called \forthb{EXIT}\index{E!EXIT}
\end{description}
\forth{\bs} is pronounced ``skip-line.'' It causes the
\Forth{} interpreter to ignore everything to the right of it on the
same line. (Since \forth{\bs} is a \Forth{} word, it must be followed
by a space.) It does not require a delimiter.

In \Fig{fig5-1}, you see \forth{\bs} used in two ways: to begin the
screen-comment line (Line 0), and to begin comments on individual
lines which have no more code to the right of the comment.

During testing, \forth{\bs} also serves to temporarily ``paren out''
lines that already contain a right parenthesis in a name or comment.
For instance, these two ``skip-line''s keep the definition of
\forth{NUTATE} from being compiled without causing problems in
encountering either right parenthesis:
\begin{Code}
\ : nutate  ( x y z )
\   swap rot  (nutate) ;
\end{Code}
\forthb{\bs S} is pronounced ``skip-screen.'' It causes the \Forth{}
interpreter to stop interpreting the screen entirely, as though there
were nothing else in the screen beyond \forthb{\bs S}.

In many \Forth{} systems, this function is the same as
\forthb{EXIT},\index{E!EXIT} which is the run-time routine for
semicolon.  In these systems the use of \forthb{EXIT} is acceptable.
Some \Forth{} systems, however, require for internal reasons a
different routine for the ``skip-screen'' function.

Definitions for \forthb{\bs} and \forthb{\bs S} can be found in \App{C}.%
\index{L!Load screens!application|)}

\subsection{Chapter-load Screens}%
\index{L!Load screens!chapter|(}%
\index{C!Chapter-load screens|(}

\Fig{fig5-2} illustrates a typical chapter-load screen.  The screens
loaded by this screen are referred to relatively, not absolutely as
they were in the application-load screen.

This is because the chapter-load screen is the first screen of the
contiguous range of screens in the chapter.  You can move an entire
chapter forward or backward within the listing; the relative pointers
in the chapter-load screen are position-independent.  All you have to
change is the single number in the application-load screen that points
to the beginning of the chapter.
%Page 140 in first edition.

\begin{figure*}
\caption{Example of a chapter-load screen.}
\labelfig{fig5-2}

\setcounter{screen}{100}
\begin{Screen}
\ GRAPHICS                 Chapter load                 07/11/83

 1 fh load            \ dot-drawing primitive
 2 fh 3 fh thru       \ line-drawing primitives
 4 fh 7 fh thru       \ scaling, rotation
 8 fh load            \ box
 9 fh 11 fh thru      \ circle



corner  \ initialize relative position to low-left corner





\end{Screen}
\end{figure*}

\index{R!Relative loading|(}%
\begin{tip}
Use absolute screen numbers in the application-load screen.  Use
relative screen numbers in the chapter- or section-load screens.
\end{tip}
There are two ways to implement relative loading.
The most common is to define:
\begin{Code}
: +load  ( offset -- )  blk @ +  load ;
\end{Code}
and
\begin{Code}
: +thru  ( lo-offset hi-offset -- )
     1+ swap DO  i +load  LOOP ;
\end{Code}
My own way, which I submit as a more useful factoring, requires a
single word, \forthb{FH} (see \App{C} for its definition).

The phrase
\begin{Code}
1 fh load
\end{Code}
is read ``1 from here \forth{LOAD},'' and is equivalent
to \forth{1 +LOAD}.

Similarly,
\begin{Code}
2 fh   5 fh thru
\end{Code}
is read ``2 from here, 5 from here \forth{THRU}.''

Some programmers begin each chapter with a dummy word; e.g.,
\begin{Code}
: video-io ;
\end{Code}
%Page 141 in first edition.
and list its name in the comment on the line where the chapter is
loaded in the application-load screen.  This permits selectively
\forth{FORGET}ting any chapter and reloading from that point on
without having to look at the chapter itself.

Within a chapter the first group of screens will usually define those
variables, constants, and other data structures needed globally within
the chapter.  Following that will come the lexicons, loaded in
``uses'' order.  The final lines of the chapter-load screen normally
invoke any needed initialization commands.

\index{M!Moore Products Company|(}%
Some of the more style-conscious \Forth{}wrights begin each chapter
with a ``preamble'' that discusses in general terms the theory of
operation for the components described in the chapter.  \Fig{fig5-3}
is a sample preamble screen which demonstrates the format required at
Moore Products Co.

\begin{figure*}[tttt]
\caption{Moore Products Co.'s format for chapter preambles.}
\labelfig{fig5-3}
\begin{Screen}
CHAPTER 5  -  ORIGIN/DESTINATION - MULTILOOP BIT ROUTINES

DOCUMENTS - CONSOLE STRUCTURE CONFIGURATION
        DESIGN SPECIFICATION
        SECTIONS - 3.2.7.5.4.1.2.8
                   3.2.7.5.4.1.2.10

ABSTRACT  -  File control types E M T Q and R can all
             originate from a Regional Satellite or a
             Data Survey Satellite.  These routines allow
             the operator to determine whether the control
             originated from a Regional Satellite or not.




\end{Screen}

\begin{Screen}
CHAPTER NOTES - Whether or not a point originates from
                a Regional Satellite is determined by
                the Regional bit in BITS, as follows:

                  1 = Regional Satellite
                  2 = Data Survey Satellite

                 For the location of the Regional bit
                 in BITS, see the Design Specification
                 Section - 3.2.7.5.4.1.2.10

HISTORY  -




\end{Screen}
\end{figure*}%
\index{M!Moore Products Company|)}

%Page 142 in first edition.
\begin{interview}
\person{Charles Moore}\index{M!Moore, Charles|(} (no relation to Moore
Products Co.) places less importance on the well-organized
hierarchical listing than I do. \person{Moore}:

\begin{tfquot}
I structure \emph{applications} hierarchically, but not necessarily
\emph{listings.}  My listings are organized in a fairly sloppy way,
not at all hierarchically in the sense of primitives first.

I use \forthb{LOCATE} {[}also known as \forthb{VIEW}; see the Handy Hint
in \emph{Starting \Forth{},} Chapter Nine{]}.  As a result, the
listing is much less carefully organized because I have \forthb{LOCATE}
to find things for me.  I never look at listings.
\end{tfquot}\index{M!Moore, Charles|)}
\end{interview}


\subsection{--\,--> vs.\ THRU}%
\index{T!THRU|(}

\index{N!Next block|(}%
On the subject of relative loading, one popular way to load a series
of adjacent screens is with the word \forth{-{}->} (pronounced ``next
block'').  This word causes the interpreter to immediately cease
interpreting the current screen and begin interpreting the next
(higher-numbered) screen.

If your system provides \forth{-{}->}, you must choose between using
the \forthb{THRU} command in your chapter-load screen to load each
series of screens, or linking each series together with the arrows and
\forth{LOAD}ing only the first in the series.  (You can't do both;
you'd end up loading most of the screens more than once.)%
\index{T!THRU|)}

The nice thing about the arrows is this: suppose you change a screen
in the middle of a series, then reload the screen.  The rest of the
series will automatically get loaded.  You don't have to know what the
last screen is.

That's also the nasty thing about the arrows: There's no way to stop
the loading process once it starts.  You may compile a lot more
screens than you need to test this one screen.%
\index{N!Next block|)}

To get analytical about it, there are three things you might want to
do after making the change just described:

\begin{enumerate}
\item load the one screen only, to test the change,
\item load the entire section in which the screen appears,
\suspend{enumerate}
or
\resume{enumerate}
\item load the entire remainder of the application.
\end{enumerate}
The use of \forthb{THRU} seems to give you the greatest control.

Some people consider the arrow to be useful for letting definitions
cross screen boundaries.  In fact \forth{-{}->} is the only way to
compile a high-level (colon) definition that occupies more than one
screen, because \forth{-{}->} is ``immediate.'' But it's \emph{never}
good style to let a colon definition cross screen boundaries.  (They
should never be that long!)

On the other hand, an extremely complicated and time-critical piece
of assembler coding might occupy several sequential screens.  In this
case, though, normal \forthb{LOAD}ing will do just as well, since the
assembler does not use compilation mode, and therefore does not
require immediacy.

Finally, the arrow wastes an extra line of each source screen.  We
don't recommend it.%
\index{R!Relative loading|)}%
\index{L!Load screens!chapter|)}%
\index{C!Chapter-load screens|)}%
\index{L!Load screens|)}%
\index{L!Listing organization|)}

%Page 143 in first edition.
\subsection{An Alternative to Screens: Source in Named Files}%
\index{N!Named files, storing source code in|(}

\index{F!File-based system|(}%
Some \Forth{} practitioners advocate storing source code in
variable-length, named text files, deliberately emulating the approach
used by traditional compilers and editors.  This approach may become
more and more common, but its usefulness is still controversial.

Sure, it's nice not to have to worry about running out of room in a
screen, but the hassle of writing in a restricted area is compensated
for by retaining control of discrete chunks of code.  In developing an
application, you spend a lot more time loading and reloading screens
than you do rearranging their contents.

``Infinite-length'' files allow sloppy, disorganized thinking and bad
factoring.  Definitions become longer without the discipline imposed
by the 1K block boundaries.  The tendency becomes to write a 20K file,
or worse: a 20K definition.

Perhaps a nice compromise would be a file-based system that allows
nested loading, and encourages the use of very small named files.
Most likely, though, the more experienced \Forth{} programmers would
not use named files longer than 5K to 10K.  So what's the benefit?%
\index{F!File-based system|)}

Some might answer that rhetorical question: ``It's easier to remember
names than numbers.'' If that's so, then predefine those block numbers
as constants, e.g.:
\begin{Code}
90 Constant framing
\end{Code}
Then to load the ``framing'' section, enter
\begin{Code}
framing load
\end{Code}
Or, to list the section's load block, enter
\begin{Code}
framing list
\end{Code}
(It's a convention that names of sections end in ``ING.'')

Of course, to minimize the hassle of the screen-based approach you
need good tools, including editor commands that move lines of source
from one screen to another, and words that slide a series of screens
forward or back within the listing.%
\index{N!Named files, storing source code in|)}

\subsection{Disk Partitioning}%
\index{D!Disk partitioning|(}
The final aspect of the well-organized listing involves standardizing
an arrangement for what goes where on the disk.  These standards must
be set by each shop, or department, or individual programmer,
depending on the nature of the work.
%Page 144 in first edition.

\begin{figure*}
\caption{Example of a disk-partitioning scheme within one department.}
\labelfig{fig5-4}

\begin{description}
\item[Screen 0] is the title screen, showing the name of the
    application, the current release number, and primary author.
\item[Screen 1] is the application-load block.
\item[Screen 2] is reserved for possible continuation from Screen 1
\item[Screen 4 and 5] contain system messages.
\item[Screens 9 thru 29] incorporate general utilities needed
    in, but not restricted to, this application.
\item[Screen 30] begins the application screens.
\end{description}
\end{figure*}

\Fig{fig5-4} shows a typical department's partitioning scheme.

In many \Forth{} shops it's considered desirable to begin sections of
code on screen numbers that are evenly divisible by three.  Major
divisions on a disk should be made on boundaries evenly divisible by
thirty.%
\index{D!Disk partitioning|)}

The reason? By convention, \Forth{} screens are printed three to a
page, with the top screen always evenly divisible by three.  Such a
page is called a ``triad;'' most \Forth{} systems include the word
\forth{TRIAD} to produce it, given as an argument the number of any of
the three screens in the triad.  For instance, if you type
\begin{Code}
77 triad
\end{Code}
you'll get a page that includes 75, 76, and 77.

The main benefit of this convention is that if you change a single
screen, you can slip the new triad right into your binder containing
the current listing, replacing exactly one page with no overlapping
screens.

Similarly, the word \forth{INDEX} lists the first line of each screen,
60 per page, on boundaries evenly divisible by 60.\index{I!INDEX}

\index{S!Screens!numbering|(}%
\begin{tip}
Begin sections or lexicons on screen numbers evenly divisible by three.
Begin applications or chapters on screen numbers evenly divisible by
thirty.
\end{tip}%
\index{S!Screens!numbering|)}

\subsection{Electives}%
\index{E!Electives|(}
Vendors of \Forth{} systems have a problem.  If they want to include
every command that the customer might expect---words to control
graphics, printers, and other niceties---they often find that the system
has swollen to more than half the memory capacity of the computer,
leaving less room for serious programmers to compile their
applications.
%Page 145 in first edition.

The solution is for the vendor to provide the bare bones as a
precompiled nucleus, with the extra goodies provided in \emph{source} form.
This approach allows the programmer to pick and choose the special
routines actually needed.

These user-loadable routines are called ``electives.'' Double-length
arithmetic, date and time support, \forth{CASE} statements and the
\forth{DOER}/\hy \forth{MAKE} construct (described later) are some of
the features that \Forth{} systems should offer as electives.%
\index{E!Electives|)}%
\index{I!Implementation!listing organization|)}

\section{Screen Layout}%
\index{S!Screens!layout|(}%
\index{I!Implementation!screen layout|(}

In this section we'll discuss the layout of each source screen.

\index{C!Comment line|(}%
\begin{tip}
Reserve Line 0 as a ``comment line.''
\end{tip}
The comment line serves both as a heading for the screen, and also as
a line in the disk \forth{INDEX}.  It should describe the purpose of
the screen (not list the words defined therein).

The comment line minimally contains the name of the screen.  In larger
applications, you may also include both the chapter name and screen
name.  If the screen is one of a series of screens implementing a
lexicon, you should include a ``page number'' as well.

\index{S!Stamp|(}%
\index{D!Dates, representation of|(}
The upper right hand corner is reserved for the ``stamp.'' The stamp
includes the date of latest revision and, when authorship is
important, the programmer's initials (three characters to the left of
the date); e.g.:
\begin{Code}
( Chapter name        Screen Name -- pg #      JPJ 06/10/83)
\end{Code}
Some \Forth{} editors will enter the stamp for you at the press of a key.

A common form for representing dates is
\begin{Code}
mm-dd-yy
\end{Code}
that is, February 6, 1984 would be expressed
\begin{Code}
02-06-84
\end{Code}
An increasingly popular alternative uses
\begin{Code}
ddMmmyy
\end{Code}
where ``Mmm'' is a three-letter abbreviation of the month.  For instance:
\begin{Code}
22Oct84
\end{Code}
%Page 146 in first edition.
This form requires fewer characters than
\begin{Code}
10-22-84
\end{Code}
and eliminates possible confusion between dates and months.%
\index{S!Stamp|)}%
\index{D!Dates, representation of|)}

If your system has \forth{\bs} (``skip-line''---see \App{C}), you can
write the comment line like this:
\begin{Code}
\ Chapter name        Screen Name -- pg.#       JPJ 06/10/83
\end{Code}
As with all comments, use lower-case or a mixture of lower- and
upper-case text in the comment line.

One way to make the index of an application reveal more about the
organization of the screens is to indent the comment line by three
spaces in screens that continue a lexicon.  \Fig{fig5-5} shows a
portion of a list produced by \forthb{INDEX} in which the comment lines
for the continuing screens are indented.%
\index{C!Comment line|)}

\begin{figure*}[bbbb]
\caption{The output of \forth{INDEX} showing indented comment lines.}
\labelfig{fig5-5}
\begin{Code}
 90 \ Graphics           Chapter load               JPJ 06/10/83
 91    \ Dot-drawing primitives                     JPJ 06/10/83
 92 \ Line-drawing primitives                       JPJ 06/11/83
 93    \ Line-drawing primitives                    JPJ 06/10/83
 94    \ Line-drawing primitives                    JPJ 09/02/83
 95 \ Scaling, rotation                             JPJ 06/10/83
 96    \ Scaling, rotation                          JPJ 02/19/84
 97    \ Scaling, rotation                          JPJ 02/19/84
 98    \ Scaling, rotation                          JPJ 02/19/84
 99 \ Boxes                                         JPJ 06/10/83
100 \ Circles                                       JPJ 06/10/83
101    \ Circles                                    JPJ 06/10/83
102    \ Circles                                    JPJ 06/10/83
\end{Code}
\end{figure*}

\begin{tip}
Begin all definitions at the left edge of the screen, and define only
one word per line.
\end{tip}
%! There should be no page breaks between the text and code
\noindent \emph{Bad:}
\begin{Code}
: arriving   ." Hello" ;   : departing   ." Goodbye" ;
\end{Code}
\noindent \emph{Good:}
\begin{Code}
: arriving   ." Hello" ;
: departing   ." Goodbye" ;
\end{Code}
This rule makes it easier to find a definition in the listing.  (When
definitions continue for more than one line, the subsequent lines
should always be indented.)
%Page 147 in first edition.

\forthb{VARIABLE}s and \forthb{CONSTANT}s should also be defined one per
line.  (See ``Samples of Good Commenting Style'' in \App{E}.) This
leaves room for an explanatory comment on the same line.  The
exception is a large ``family'' of words (defined by a common
defining-word) which do not need unique comments:
\begin{Code}
0 Hue black     1 Hue blue      2 Hue green
3 Hue cyan      4 Hue red       5 Hue magenta
\end{Code}
\begin{tip}
Leave lots of room at the bottom of the screen for later additions.
\end{tip}
On your first pass, fill each screen no more than half with code.  The
iterative approach demands that you sketch out the components of your
application first, then iteratively flesh them out until all the
requirements are satisfied.  Usually this means adding new commands,
or adding special-case handling, to existing screens.  (Not
\emph{always,} though.  A new iteration may see a simplification of
the code. Or a new complexity may really belong in another component
and should be factored out, into another screen.)

Leaving plenty of room at the outset makes later additions more
pleasant.  One writer recommends that on the initial pass, the screen
should contain about 20--40 percent code and 80--60 percent
whitespace \cite{stevenson81}.

Don't skip a line between each definition.  You may, however, skip a
line between \emph{groups} of definitions.%
\index{D!DECIMAL|(}\index{B!BASE|(}
\begin{tip}
All screens must leave \forthb{BASE} set to \forthb{DECIMAL}.
\end{tip}
Even if you have three screens in a row in which the code is written
in \forthb{HEX} (three screens of assembler code, for instance), each
screen must set \forth{BASE} to \forthb{HEX} at the top, and restore
base to \forthb{DECIMAL} at the bottom.  This rule ensures that each
screen could be loaded separately, for purposes of testing, without
mucking up the state of affairs.  Also, in reading the listing you
know that values are in decimal unless the screen explicitly
says \forthb{HEX}.

Some shops take this rule even further.  Rather than brashly resetting
base to \forthb{DECIMAL} at the end, they reset base to \emph{whatever
it was at the beginning.} This extra bit of insurance can be
accomplished in this fashion:
\begin{Code}
base @       hex    \ save original BASE on stack
0A2 Constant bells
0A4 Constant whistles
... etc. ...
base !              \ restore it
\end{Code}
%Page 148 in first edition.
\noindent Sometimes an argument is passed on the stack from screen to
screen, such as the value returned by \forthb{BEGIN} or \forthb{IF} in a
multiscreen assembler definition, or the base address passed from one
defining word to another---see ``Compile-Time Factoring'' in \Chap{6}.
In these cases, it's best to save the value of \forth{BASE} on the
return stack like this:
\begin{Code}
base @ >r     hex
... etc. ...
r> base !
\end{Code}
Some folks make it a policy to use this approach on any screen that
changes \forthb{BASE}, so they don't have to worry about it.%
\index{B!BASE|)}

\person{Moore}\index{M!Moore, Charles} prefers to define \forthb{LOAD}
to invoke \forthb{DECIMAL} after loading.  This approach simplifies the
screen's contents because you don't have to worry about resetting.%
\index{D!DECIMAL|)}

\subsection{Spacing and Indentation}%
\index{S!Spacing|(}

\begin{tip}
Spacing and indentation are essential for readability.
\end{tip}
The examples in this book use widely accepted conventions of spacing
and indenting style.  Whitespace, appropriately used, lends
readability.  There's no penalty for leaving space in source screens
except disk memory, which is cheap.

For those who like their conventions in black and white, Table
\ref{tab-5-1} is a list of guidelines.  (But remember, \Forth{}'s
interpreter couldn't care less about spacing or indentation.)

\begin{table}[bbbb]
\caption{Indentation and spacing guidelines}
\label{tab-5-1}
\medskip\blackline{0pt}\medskip
\begin{minipage}{\textwidth}
\begin{quote}
1 space between the colon and the name\\
2 spaces between the name and the comment\footnote{An often-seen
alternative calls for 1 space between the name and comment and 3
between the comment and the definition.  A more liberal technique uses
3 spaces before and after the comment.  Whatever you choose, be
consistent.}\\
2 spaces, or a carriage return, after the comment and
before the definition\footnotemark[1]\\
3 spaces between the name and definition if no comment is used\\
3 spaces indentation on each subsequent line (or multiples
of 3 for nested indentation)\\
1 space between words/numbers within a phrase\\
2 or 3 spaces between phrases\\
1 space between the last word and the semicolon\\
1 space between semicolon and \forthb{IMMEDIATE} (if invoked)
\end{quote}
No blank lines between definitions, except to separate distinct groups
of definitions

%% Note: AH: Again type writer style footnotes.
\end{minipage}
\medskip\blackline{0pt}
\end{table}

%Page 149 in first edition.

The last position of each line should be blank except for:
%%!!!te original used a) b) enumeration here.
\ifeightyfour
\begin{list}{\alph{enumi})}{\usecounter{enumi}}
\else
\begin{enumerate}
\fi
\item quoted strings that continue onto the next line, or
\item the end of a comment.
\ifeightyfour
\end{list}
\else
\end{enumerate}
\fi
A comment that begins with \forth{\bs} may continue right to the end
of the line.  Also, a comment that begins with \forth{(} may have its
delimiting right parenthesis in the last column.

\index{I!Indentation|(}%
Here are some common errors of spacing and indentation:

\goodbreak\bigskip\noindent
\emph{Bad} (name not separated from the body of the definition):
\begin{Code}
: push heave ho ;
\end{Code}
\emph{Good:}
\begin{Code}
: push   heave ho ;
\end{Code}
\emph{Bad} (subsequent lines not indented three spaces):
\begin{Code}
: riddance  ( thing-never-to-darken-again -- )
darken  never again ;
\end{Code}
\emph{Good:}
\begin{Code}
: riddance  ( thing-never-to-darken-again -- )
   darken  never again ;
\end{Code}
\emph{Bad} (lack of phrasing):
\begin{Code}
: gettysburg   4 score 7 years + ago ;
\end{Code}
\goodbreak\noindent
\emph{Good:}
\begin{Code}
: gettysburg   4 score   7 years +   ago ;
\end{Code}
Phrasing is a subjective art;
I've yet to see a useful set of formal rules.\\
Simply strive for readability.%
\index{S!Spacing|)}%
\index{S!Screens!layout|)}%
\index{I!Implementation!screen layout|)}%
\index{I!Indentation|)}

\section{Comment Conventions}%
\index{C!Comment conventions|(}%
\index{I!Implementation!comment conventions|(}

Appropriate commenting is essential.  There are five types of comments:
stack-effect comments, data-structure comments, input-stream comments,
purpose comments and narrative comments.
%%!!!te Original didn't put this into a description
\begin{description}
\item[\emph{A} stack-effect comment]\index{S!Stack-effect comment}%
shows the arguments that the definition consumes from the stack, and
the arguments it returns to the stack, if any.
%Page 150 in first edition.

\item[\emph{A} data-structure comment]\index{D!Data-structure comment}%
indicates the position and meaning of elements in a data structure.
For instance, a text buffer might contain a count in the first byte,
and 63 free bytes for text.

\item[\emph{An} input-stream comment]\index{I!Input-stream comment}%
indicates what strings the word expects to see in the input stream.
For example, the \Forth{} word \forth{FORGET} scans for the name of a
dictionary entry in the input stream.

\item[\emph{A} purpose comment]\index{P!Purpose comment}%
describes, in as few words possible, what the definition does.  How
the definition works is not the concern of the purpose comment.

\item[\emph{A} narrative comment]\index{N!Narrative comments}%
appears amidst a definition to explain what is going on, usually
line-by-line.  Narrative comments are used only in the ``vertical
format,'' which we'll describe in a later section.
\end{description}

Comments are usually typed in lower-case letters to distinguish them
from source code.  (Most \Forth{} words are spelled with upper-case
letters, but lower-case spellings are sometimes used in special cases.)

In the following sections we'll summarize the standardized formats
for these types of comments and give examples for each type.

\subsection{Stack Notation}%
\index{S!Stack notation|(}
\begin{tip}
Every colon or code definition that consumes and/or returns any arguments
on the stack must include a stack-effect comment.
\end{tip}
``Stack notation'' refers to conventions for representing what's on
the stack.  Forms of stack notation include ``stack pictures,''
``stack effects,'' and ``stack-effect comments.''%
\index{S!Stack notation|)}%
\index{P!Purpose comment}

\subsection{Stack Picture}%
\index{S!Stack picture|(}

A stack picture depicts items understood to be on the stack at a given
time.  Items are listed from left to right, with the leftmost item
representing the bottom of the stack and the rightmost item
representing the top.

For instance, the stack picture
\begin{Code}
nl n2
\end{Code}
indicates two numbers on the stack, with n2 on the top (the most
accessible position).

This is the same order that you would use to type these values in;
i.e., if n1 is 100 and n2 is 5000, then you would type
\begin{Code}
100 5000
\end{Code}
to place these values correctly on the stack.

%Page 151 in first edition.
A stack picture can include either abbreviations, such as ``n1,'' or
fully spelled-out words.  Usually abbreviations are used.  Some
standard abbreviations appear in Table \ref{tab-5-2}.  Whether
abbreviations or fully spelled-out words are used, each stack item
should be separated by a space.

If a stack item is described with a phrase (such as
``address-of-latest-link''), the words in the phrase should be joined
by hyphens.  For example, the stack picture:
\begin{Code}
address current-count max-count
\end{Code}
shows three elements on the stack.%
\index{S!Stack picture|)}

\subsection{Stack Effect}%
\index{S!Stack effect|(}

A ``stack effect'' shows two stack pictures: one picture of any items
that may be \emph{consumed} by a definition, and another picture of
any items \emph{returned} by the definition.  The ``before'' picture
comes first, followed by two hyphens, then the ``after'' picture.

For instance, the stack effect for \Forth{}'s addition operator,
\forth{+} is
\begin{Code}
n n -- sum
\end{Code}
where \forth{+} consumes two numbers and returns their sum.

Remember that the stack effect describes only the \emph{net result} of
the operation on the stack.  Other values that happen to reside on the
stack beneath the arguments of interest don't need to be shown.  Nor
do values that may appear or disappear while the operation is
executing.

If the word returns any input arguments unchanged, they
should be repeated in the output picture; e.g.,
\begin{Code}
3rd 2nd top-input -- 3rd 2nd top-output
\end{Code}
Conversely, if the word changes any arguments, the stack comment must
use a different descriptor:
\begin{Code}
nl -- n2
n -- n'
\end{Code}
A stack effect might appear in a formatted glossary.%
\index{S!Stack effect|)}

\subsection{Stack Effect Comment}%
\index{S!Stack-effect comment|(}

A ``stack-effect comment'' is a stack effect that appears in source
code surrounded by parentheses.  Here's the stack-effect comment for
the word \forth{COUNT}:
\begin{Code}
( address-of-counted-string -- address-of-text count)
\end{Code}
%Page 152 in first edition.
or:
\begin{Code}
( 'counted-string -- 'text count)
\end{Code}
(The ``count'' is on top of the stack after the word has executed.)

If a definition has no effect on the stack (that is, no effect the
user is aware of, despite what gyrations occur within the definition),
it needs no stack-effect comment:
\begin{Code}
: BAKE   COOKIES OVEN ! ;
\end{Code}
On the other hand, you may want to use an empty stack comment---i.e.,
\begin{Code}
: BAKE   ( -- )  COOKIES OVEN ! ;
\end{Code}
to emphasize that the word has no effect on the stack.

If a definition consumes arguments but returns none, the double-hyphen
is optional.  For instance,
\begin{Code}
( address count -- )
\end{Code}
can be shortened to
\begin{Code}
( address count)
\end{Code}
The assumption behind this convention is this: There are many more
colon definitions that consume arguments and return nothing than
definitions that consume nothing and return arguments.%
\index{S!Stack-effect comment|)}

\subsection{Stack Abbreviation Standards}%
\index{S!Stack abbreviation standards|(}

Abbreviations used in stack notation should be consistent. Table
\ref{tab-5-2} lists most of the commonly used abbreviations.  (This
table reappears in \App{E}.) The terms ``single-length,''
``double-length,'' etc. refer to the size of a ``cell'' in the
particular \Forth{} system.  (If the system uses a 16-bit cell, ``n''
represents a 16-bit number; if the system uses a 32-bit cell, ``n''
represents a 32-bit number.)%
\index{S!Stack abbreviation standards|)}

\subsection{Notation of Flags}

Table \ref{tab-5-2} shows three ways to represent a boolean flag.  To
illustrate, here are three versions of the same stack comment for the
word \forth{-TEXT}:
\begin{Code}
( at u a2 -- ?)
( at u a2 -- t=no-match)
( at u a2 -- f=match)
\end{Code}
%Page 153 in first edition.
\begin{table}[hhhh]
\caption{Stack-comment abbreviations.}
\label{tab-5-2}
\vspace{1ex}
\blackline{1ex}
\begin{tabular}{@{\hspace{2.5em}}ll}
n             &  single-length signed number \\
d             &  double-length signed number \\
u             &  single-length unsigned number \\
ud            &  double-length unsigned number \\
t             &  triple-length \\
q             &  quadruple-length \\
c             &  7-bit character value \\
b             &  8-bit byte \\
?             &  boolean flag; or; \\
\quad t=         &  true \\
\quad f=         &  false \\
a or adr      &  address \\
acf           &  address of code field \\
apf           &  address of parameter field \\
'             &  (as prefix) address of \\
s d           &  (as a pair) source destination \\
lo hi         &  lower-limit upper-limit (inclusive) \\
\#            &   count \\
o             &  offset \\
i             &  index \\
m             &  mask \\
x             &  don't care (data structure notation) \\
\end{tabular}
\smallskip

An ``offset'' is a difference expressed in absolute units, such as bytes.\\
An ``index'' is a difference expressed in logical units, such as
elements or records.
\vspace{0ex}
\blackline{0ex}
\end{table}
The equal sign after the symbols ``t'' and ``f'' equates the flag
outcome with its meaning.  The result-side of the second version would
be read ``true means no match.''

\subsection{Notation of Variable Possibilities}%
\index{V!Variable possibilities, notation of|(}
Some definitions yield a different stack effect under different
circumstances.

If the number of items on the stack remains the same under all
conditions, but the items themselves change, you can use the vertical
bar ( \forth{|} ) to mean ``or.'' The following stack-effect comment
describes a word that returns either the address of a file or, if the
requested file is not found, zero:
\begin{Code}
( -- address|0=undefined-file)
\end{Code}
If the number of items in a stack picture can vary---in either the
``before'' or ``after'' picture---you must write out both versions of
the entire stack
%Page 154 in first edition.
picture, along with the double-hyphen, separated by the ``or'' symbol.
For instance:
\begin{Code}
-find   ( -- apf len t=found | -- f=not-found )
\end{Code}
This comment indicates that if the word is found, three arguments are
returned (with the flag on top); otherwise only a false flag is
returned.

Note the importance of the second ``-\,-''.  Its omission would indicate
that the definition always returned three arguments, the top one being
a flag.

\index{S!Stack-effect comment|(}%
If you prefer, you can write the entire stack effect twice, either on
the same line, separated by three spaces:
\begin{Code}
?dup   \ if zero: ( n -- n)    if non-zero:( n -- n n)
\end{Code}
or listed vertically:
\begin{Code}
-find  \     found:( -- apf len t )
       \ not-found:( -- f )
\end{Code}
\index{S!Stack-effect comment|)}%
\index{V!Variable possibilities, notation of|)}

\subsection{Data-Structure Comments}%
\index{D!Data-structure comment|(}

A ``data-structure comment'' depicts the elements in a data structure.
For example, here's the definition of an insert buffer called
\forth{|INSERT} :

\begin{Code}
Create |insert  64 allot  \  { 1# | 63text }
\end{Code}
The ``faces'' (curly-brackets) begin and end the structure comment;
the bars separate the various elements in the structure; the numbers
represent bytes per element.  In the comment above, the first byte
contains the count, and the remaining 63 bytes contain the text.

A ``bit comment'' uses the same format as a data-structure comment to
depict the meaning of bits in a byte or cell.  For instance, the bit
comment
\begin{Code}
{ 1busy? | 1acknowledge? | 2x | 6input-device |
   6output-device }
\end{Code}
describes the format of a 16-bit status register of a communications
channel.  The first two bits are flags,\index{F!Flags}
the second two bits are unused, and the final pair of six-bit fields
indicate the input and output devices which this channel is connected
to.

If more than one data structure employs the same pattern of elements,
write out the comment only once (possibly in the preamble), and
%Page 155 in first edition.
give a name to the pattern for reference in subsequent screens.  For
instance, if the preamble gives the above bit-pattern the name
``status,'' then ``status'' can be used in stack comments to indicate
values with that pattern:
\begin{Code}
: status?  ( -- status) ... ;
\end{Code}
If a \forthb{2VARIABLE} contains one double-length value, the comment
should be a stack picture that indicates the contents:
\begin{Code}
2Variable price  \ price in cents
\end{Code}
If a \forthb{2VARIABLE} contains two single-length data elements, it's
given a stack picture showing what would be on the stack after a
\forth{2@}. Thus:
\begin{Code}
2Variable measurements  ( height weight )
\end{Code}
This is different from the comment that would be used if
\forth{MEASUREMENTS} were defined by \forthb{CREATE}.
\begin{Code}
Create measurements  2 cells allot    \ { 2weight | 2height }
\end{Code}
(While both statements produce the same result in the dictionary, the
use of \forthb{2VARIABLE} implies that the values will normally be
``2-fetched'' and ``2-stored'' together-thus we use a \emph{stack}
comment.  The high-order part, appearing on top of the stack, is
listed to the right.  The use of \forthb{CREATE} implies that the
values will normally be fetched and stored separately--thus we use a
data structure comment.  The item in the 0th position is listed to the
left.)%
\index{D!Data-structure comment|)}

\subsection{Input-stream Comments}%
\index{I!Input-stream comment|(}

The input-stream comment indicates what words and/or strings are
presumed to be in the input stream. Table \ref{tab-5-3} lists the
designations used for input stream arguments.

\begin{table*}[hhhh]
\caption{Input-stream comment designations.}
\label{tab-5-3}
\vspace{1ex}\blackline{1ex}
\centerline{\begin{tabular}{ll}
c     &  single character, blank-delimited \\
name  &  sequence of characters, blank delimited \\
text  &  sequence of characters, delimited by non-blank \\
\end{tabular}}

\medskip
Follow ``text'' with the actual delimiter required in angular brackets; e.g.:
\forth{"text<">"} or \forth{"text<)>"}
\vspace{1ex}\blackline{0ex}
\end{table*}
%% Note: AH : typewriter style footnote with *
%% Note: AH : text" and text) are literal examples,
%%    and should be slanted or such.
The input-stream comment appears \emph{within} the stack comment, and
is \emph{not} encapsulated between its own pair of parentheses, but
simply surrounded
%Page 156 in first edition.
by quotes on each side.  For instance, here's one way to comment
the definition of \forth{'} (tick) showing the input-stream comment,
together with the stack comment:
\begin{Code}
: '   ( "name" -- a )
\end{Code}
\index{S!String input, receiving|(}%
Incidentally, there are three distinct ways to receive string input.
To avoid confusion, here are the terms:

%%!!!te Original had bullet points here + description
\begin{description}
\item[Scanning-for]\index{S!Scanning-for}%
means looking ahead in the input stream, either for a word or number
as in the case of tick, or for a delimiter as in the case of
\forth{."} and \forth{(} .
\item[Expecting]\index{E!Expecting}%
means waiting for. \forth{EXPECT} and \forth{KEY}, and definitions
that invoke them, are ones that ``expect'' input.
\item[Presuming]\index{P!Presuming}%
indicates that in normal usage something will follow.  The word:
``scans-for'' the name to be defined, and ``presumes'' that a
definition will follow.
\end{description}
The input-stream comment is only appropriate for input being scanned-for.%
\index{S!String input, receiving|)}%
\index{I!Input-stream comment|)}

\subsection{Purpose Comments}%
\index{P!Purpose comment|(}

\begin{tip}
Every definition should bear a purpose comment unless:
\medskip
%%!!!te Original had a. b. enumeration
\begin{enumerate}
\item its purpose is clear from its name or its stack-effect comment, or
\item if it consists of three or fewer words.
\end{enumerate}
\end{tip}
The purpose comment should be kept to a minimum-never more than a full
line.  For example:
\begin{Code}
: cold   \ restore system to start condition
    ... ;
\end{Code}
Use the imperative mood: ``set Foreground color,'' not ``sets
Foreground color.''

On the other hand, a word's purpose can often be described in terms of
its stack-effect comment.  You rarely need both a stack comment and a
purpose comment.  For instance:
\begin{Code}
: spaces  ( #)   ... ;
\end{Code}
%Page 157 in first edition.
or
\begin{Code}
: spaces  ( #spaces-to-type -- )   ... ;
\end{Code}
This definition takes as its incoming argument a number that
represents the number of spaces to type.
\begin{Code}
: element  ( element# -- 'element )  cells  table + ;
\end{Code}
This definition converts an index, which it consumes, into an address
within a table of 2-byte elements corresponding to the indexed element.
\begin{Code}
: pad  ( -- 'scratch-pad )  here  80 + ;
\end{Code}
This definition returns an address of a scratch region of memory.

Occasionally, readability is best served by including both types of
comment. In this case, the purpose comment should appear last.  For
instance:
\begin{Code}
: block  ( n -- a )  \   ensure block n in buffer at a
\end{Code}

\begin{tip}
  Indicate the type of comment by ordering: input-stream and stack
  comments first, purpose comments last.
\end{tip}
For example:
\begin{Code}
: get   ( "name" -- a ) \  get first match
\end{Code}
If you prefer to use \forth{(}, then write:
\begin{Code}
: get   ( "name" -- a )    ( get first match)
\end{Code}
If necessary, you can put the purpose comment on a second line:
\begin{Code}
: word  ( c "name<c>" -- a )
   \ scan for string delimt'd by "c"; leave at a
   ...  ;
\end{Code}
\index{P!Purpose comment|)}%

\subsection{Comments for Defining Words}%
\index{D!Defining words:!comments for|(}
The definition of a defining word involves two behaviors:

\begin{itemize}
\item that of the defining word as it defines its ``child''
(compile-time behavior), and
\item that of the child itself (run-time behavior).
\end{itemize}
%Page 158 in first edition.
These two behaviors must be commented separately.

\index{C!Compiling words, comments for|(}%
\begin{tip}
Comment a defining word's compile-time behavior in the usual way;
comment its run-time behavior separately, following the word
\forthb{DOES>} (or \forthb{;CODE}).
\end{tip}
For instance,
\begin{Code}
: Constant  ( n ) Create ,
   DOES>  ( -- n)  @ ;
\end{Code}
The stack-effect comment for the run-time (child's) behavior
represents the net stack effect for the child word.  Therefore it does
not include the address returned by \forthb{DOES>,} even though this
address is on the stack when the run-time code begins.

\bigskip\noindent
\emph{Bad} (run-time comment includes apf):
\begin{Code}
: array   ( "name" #cells -- )
   Create cells allot
   DOES>   ( i apf -- 'cell )  swap  cells + ;
\end{Code}
\goodbreak\noindent
\emph{Good:}
\begin{Code}
: array   ( "name" #cells -- )
   Create cells allot
    DOES>  ( i -- 'cell )  swap  cells + ;
\end{Code}
Words defined by this word \forth{ARRAY} will exhibit the stack effect:
\begin{Code}
( i -- 'cell)
\end{Code}
If the defining word does not specify the run-time behavior, there still
exists a run-time behavior, and it may be commented:
\begin{Code}
: Variable   (  name  ( -- )  Create  1 cells allot ;
   \ DOES>   ( -- adr )
\end{Code}
\index{D!Defining words:!comments for|)}%

\subsection{Comments for Compiling Words}
As with defining words, most compiling words involve two behaviors:
\begin{enumerate}
\item That of the compiling word as the definition in which it appears
is compiled
\item That of the run-time routine which will execute when we invoke
the word being defined.  Again we must comment each behavior
separately.
\end{enumerate}
%Page 159 in first edition.

\begin{tip}
Comment a compiling word's run-time behavior in the usual way; comment
its compile-time behavior separately, beginning with the label
``Compile:''.
\end{tip}
For instance:
\begin{Code}
: IF   ( ? -- ) ...
\ Compile:   ( -- address-of-unresolved-branch)
   ... ; immediate
\end{Code}
In the case of compiling words, the first comment describes the
run-time behavior, which is usually the \emph{syntax for using} the
word.  The second comment describes what the word \emph{actually does}
in compiling (which is of less importance to the user).

Other examples:
\begin{Code}
: abort"  ( ? -- )
\ Compile:   text"   ( -- )
\end{Code}
Occasionally a compiling word may exhibit a different behavior when it
is invoked \emph{outside} a colon definition.  Such words (to be
fastidious about it) require three comments.  For instance:
\begin{Code}
: ASCII  ( -- c)
\ Compile:   c   ( -- )
\ Interpret:   c   ( -- c )
     ... ; immediate
\end{Code}
\App{E} includes two screens showing good commenting style.%
\index{C!Comment conventions|)}%
\index{C!Compiling words, comments for|)}%
\index{I!Implementation!comment conventions|)}

\section{Vertical Format vs.\ Horizontal Format}%
\index{V!Vertical format vs. horizontal format|(}%
\index{I!Implementation!vertical format vs. horizontal format|(}
The purpose of commenting is to allow a reader of your code to easily
determine what's going on.  But how much commenting is necessary? To
determine the level of commenting appropriate for your circumstances,
you must ask yourself two questions:

%%!!! this didn't have any bullet points or whatever in the first edition
\begin{itemize}
\expandafter\item\ifeightyfour[]\fi Who will be reading my code?
\expandafter\item\ifeightyfour[]\fi How readable are my definitions?
\end{itemize}%
\index{N!Narrative comments|(}
There are two basic styles of commenting to choose from.  The first
style, often called the ``vertical format,'' includes a step-by-step
description of the process, in the manner of a well-commented assembly
language listing.  These line-by-line comments are called ``narrative
comments.''

%Page 160 in first edition.
\begin{Code}
\ CRC Checksum                                      07/15/83
: accumulate   ( oldcrc char -- newcrc)
   256 *               \ shift char to hi-order byte
   xor                 \ & xor into previous crc
   8 0 DO              \ Then for eight repetitions,
       dup 0< IF       \ if hi-order bit is "1"
          16386 xor    \ xor it with mask and
          dup +        \ shift it left one place
          1+           \ set lo-order bit to "1"
              ELSE     \ otherwise, i.e. hi-order bit is "0"
          dup +        \ shift it left one place
              THEN
       LOOP ;          \ complete the loop
\end{Code}
The other approach does not intersperse narrative comments between
code phrases.  This is called the ``horizontal format.''
\begin{Code}
: accumulate  ( oldcrc char -- newcrc)
   256 *  xor  8 0 DO  dup 0< IF
      16386 xor  dup +  1+  ELSE  dup +  THEN  LOOP ;
\end{Code}
The vertical format is preferred when a large team of programmers are
coding and maintaining the application.  Typically, such a team will
include several junior-level programmers responsible for minor
corrections.  In such an environment, diligent commenting can save a
lot of time and upset.  As \person{Johnson}\index{J!Johnson, Dave} of Moore
Products Co.  says: ``When maintaining code you are usually interested
in just one small section, and the more information written there the
better your chances for a speedy fix.''

Here are several pertinent rules required of the \Forth{} programmers
at Moore Products Co. (I'm paraphrasing):

\begin{enumerate}
\item A vertical format will be used.  Comments will appear to the
right of the source code, but may continue to engulf the next line
totally if needed.
\item There should be more comment characters than source characters.
(The company encourages long descriptive names, greater than ten
characters, and allows the names to be counted as comment characters.)
\item Any conditional structure or application word should appear on a
separate line.  ``Noise words'' can be grouped together.  Indentation
is used to show nested conditionals.
\end{enumerate}
There are some difficulties with this format, however.%
\index{L!Line-by-line commenting|(}
For one thing, line-by-line commenting is time-consuming, even with a
good screen editor.  Productivity can be stifled, especially when
stopping to write the comments breaks your chain of thought.

Also, you must also carefully ensure that the comments are up-to-date.
Very often code is corrected, the revision is tested, the change
%Page 161 in first edition.
works---and the programmer forgets to change the comments.  The more
comments there are, the more likely they are to be wrong.  If they're
wrong, they're worse than useless.

This problem can be alleviated if the project supervisor carefully
reviews code and ensures the accuracy of comments.

Finally, line-by-line commenting can allow a false sense of security.
Don't assume that because each \emph{line} has a comment, the
\emph{application} is well-com\-men\-ted.  Line-by-line commenting doesn't
address the significant aspects of a definition's operation.  What,
for instance, is the thinking behind the checksum algorithm used? Who
knows, from the narrative comments?%
\index{L!Line-by-line commenting|)}%
\index{N!Narrative comments|)}

To properly describe, in prose, the implications of a given procedure
usually requires many paragraphs, not a single phrase.  Such
descriptions properly belong in auxiliary documentation or in the
chapter preamble.

Despite these cautions, many companies find the vertical format
necessary.  Certainly a team that is newly exposed to \Forth{} should
adopt it, as should any very large team.

What about the horizontal format? Perhaps it's an issue of art vs.\@
practicality, but I feel compelled to defend the horizontal format as
equally valid and in some ways superior.

If \Forth{} code is really well-written, there should be nothing
ambiguous about it.  This means that:

\begin{itemize}
\item supporting lexicons have a well-designed syntax
\item stack inputs and outputs are commented
\item the purpose is commented (if it's not clear from the name or
stack comment)
\item definitions are not too long
\item not too many arguments are passed to a single definition via the
stack (see ``The Stylish Stack'' in \Chap{7}).
\end{itemize}
\Forth{} is simply not like other languages, in which line-by-line
commenting is one of the few things you can do to make programs more
readable.

Skillfully written \Forth{} code is like poetry, containing precise
meaning that both programmer and machine can easily read.  Your
\emph{goal} should be to write code that does not need commenting,
even if you choose to comment it.  Design your application so that the
code, not the comments, conveys the meaning.

If you succeed, then you can eliminate the clutter of excessive
commenting, achieving a purity of expression without redundant
explanations.

\wepsfigp{fig5-2}{Wiggins, proud of his commenting technique.}

\begin{tip}
The most-accurate, least-expensive documentation
is self-documenting code.
\end{tip}
%Page 162 in first edition.
Unfortunately, even the best programmers, given the pressure of a
deadline, may write working code that is not easily readable without
comments.  If you are writing for yourself, or for a small group with
whom you can verbally communicate, the horizontal format is ideal.
Otherwise, consider the vertical format.%
\index{V!Vertical format vs. horizontal format|)}%
\index{I!Implementation!vertical format vs. horizontal format|)}

\section{Choosing Names: The Art}%
\index{I!Implementation!choosing names|(}%
\index{N!Names:!choosing|(}

\begin{tfquot}
Besides a mathematical inclination, an exceptionally good mastery of
one's native tongue is the most vital asset of a competent programmer
\emph{(Prof.  \person{Edsger W. Dijkstra} \cite{dijkstra82}).}
\end{tfquot}%
\index{W!Words:!choosing names|(}
We've talked about the significance of using names to symbolize ideas
and objects in the application.  The choosing of names turns out to be
an important part of the design process.

Newcomers tend to overlook the importance of names.  ``After all,''
they think, ``the computer doesn't care what names I choose.''

But good names are essential for readability.  Moreover, the mental
exercise of summoning a one-word description bears a synergistic effect
on your perceptions of what the entity should or should not do.

\smallbreak
Here are some rules for choosing good names:
\begin{tip}
Choose names according to ``what,'' not ``how.''
\end{tip}
A definition should hide the complexities of implementation from other
definitions which invoke it.  The name, too, should hide the details
of the procedure, and instead should describe the outward appearance
or net effect.

For instance, the \Forth{} word \forthb{ALLOT} simply increments the
dictionary pointer (called \forthb{DP} or \forthb{H} in most systems).
But the name \forthb{ALLOT} is better than \forth{DP+!} because the
user is thinking of reserving space, not incrementing a pointer.

The '83 Standard adopted the name \forthb{CMOVE>} instead of the
previous name for the same function, \forthb{<CMOVE}.  The operation
makes it possible to copy a region of memory \emph{forward} into
overlapping memory.  It accomplishes this by starting with the last
byte and working \emph{backward}.  In the new name, the forwardness of
the ``what'' supersedes the backwardness of the ``how.''

\begin{tip}
Find the most expressive word.\index{E!Expressive words}
\end{tip}
%Page 164 in first edition.

\begin{tfquot}
A powerful agent is the right word.  Whenever we come upon one of
those intensely right words in a book or a newspaper the resulting
effect is physical as well as spiritual, and electrically prompt
\emph{(\person{Mark Twain}).}

The difference between the right word and the almost-right word is
like the difference between lightning and the lightning bug
\emph{(\person{Mark Twain}).}

Suit the action to the word, the word to the action
\emph{(\person{Shakespeare}, Hamlet, Act~III).}
\end{tfquot}
\person{Henry Laxen},\index{L!Laxen, Henry}
a \Forth{} consultant and author, suggests that the most important
\Forth{} development tool is a good thesaurus \cite{laxen}.%
\index{T!Thesaurus}

Sometimes you'll think of an adequate word for a definition, but it
doesn't feel quite right.  It may be months later before you realize
that you fell short of the mark.  In the Roman numeral example in
\Chap{4}, there's a word that handles the exception case: numbers that
are one-less-than the next symbol's value.  My first choice was
\forth{4-0R-9}.  That's awkward, but it was much later that I thought
of \forth{ALMOST}.

Most fig-\Forth{} systems include the word \forth{VLIST}, which lists
the names of all the words in the current vocabulary.  After many
years someone realized that a nicer name is \forth{WORDS}.  Not only
does \forth{WORDS} sound more pleasant by itself, it also works nicely
with vocabulary names.  For instance:
\begin{Code}
editor words
\end{Code}
or
\begin{Code}
assembler words
\end{Code}
On the other hand, \person{Moore}\index{M!Moore, Charles} points out
that inappropriate names can become a simple technique for encryption.%
\index{E!Encryption}
If you need to provide security when you're forced to distribute
source, you can make your code very unreadable by deliberately
choosing misleading names.  Of course, maintenance becomes impossible.

\index{P!Phrases|(}%
\begin{tip}
Choose names that work in phrases.
\end{tip}
Faced with a definition you don't know what to call, think about how the
word will be used in context.  For instance:
%%!!!te this is how it looks like in the original
%%!!!te This really seems to be a description environment
\ifeightyfour
\begin{Code}[fontfamily=cmss,commandchars=\&\{\}]
shutter open
  OPEN is the appropriate name for a word that sets a
  bit in an I/O address identified with the name
  SHUTTER.&medskip
3 BUTTON DOES IGNITION
  DOES is a good choice for a word that vectors the
  address of the function IGNITION into a table of
  functions, so that IGNITION will be executed when
  Button 3 is pushed.&medskip
SAY HELLO
  SAY is the perfect choice for vectoring HELLO into an
  execution variable.  (When i first wrote this example
  FOR Starting &Forth{}, i called it VERSION. &person{Moore}
  reviewed the manuscript and suggested SAY, which is
  clearly much better.)&medskip
I'M HARRY
  The word I'M seems more natural than LOGON HARRY,
  LOGIN HARRY or SESSION HARRY, as often seen.
\end{Code}
\else
\begin{description}
\item[\forth{shutter open}]~

  \forth{OPEN} is the appropriate name for a word that sets a
  bit in an I/O address identified with the name
  \forth{SHUTTER}.
\item[\forth{3 button does ignition}]~

  \forth{DOES} is a good choice for a word that vectors the
  address of the function \forth{IGNITION} into a table of
  functions, so that \forth{IGNITION} will be executed when
  Button 3 is pushed.
\item[\forth{say hello}]~

  \forth{SAY} is the perfect choice for vectoring \forth{HELLO} into an
  execution variable.  (When I first wrote this example
  for Starting \Forth{}, I called it \forth{VERSION}. \person{Moore}
  reviewed the manuscript and suggested \forth{SAY}, which is
  clearly much better.)
\item[\forth{i'm harry}]~

  The word \forth{I'M} seems more natural than \forth{LOGON HARRY},
  \forth{LOGIN HARRY} or \forth{SESSION HARRY}, as often seen.
\end{description}
\fi

\index{M!Moore, Charles|(}%
\begin{interview}
The choice of \forth{I'M} is another invention of \person{Moore}, who
says:

\begin{tfquot}
I detest the word \forth{LOGON}. There is no such word in English.  I
was looking for a word that said, ``I'm \dots{}'' It was a natural.
I just stumbled across it.  Even though it's clumsy with that
apostrophe, it has that sense of rightness.

All these little words are the nicest way of getting the ``Aha!''
reaction.  If you think of the right word, it is \emph{obviously} the
right word.

If you have a wide recall vocabulary, you're in a better position to
come up with the right word.
\end{tfquot}
\end{interview}\index{M!Moore, Charles|)}%
Another of \person{Moore}'s favorite words is \forth{TH}, which he
uses as an array indexing word.  For instance, the phrase
\begin{Code}
5 th
\end{Code}
returns the address of the ``fifth'' element of the array.%
\index{P!Phrases|)}

\index{S!Spelled-out names|(}%
\begin{tip}
Spell names in full.
\end{tip}
I once saw some \Forth{} code published in a magazine in which the
author seemed hell-bent on purging all vowels from his names,
inventing such eyesores as \forth{DSPL-BFR} for ``display buffer.''
Other writers seem to think that three characters magically says it
all, coining \forth{LEN} for ``length.'' Such practices reflect
thinking from a bygone age.

\index{A!Abbreviations|(}%
\Forth{} words should be fully spelled out.  Feel proud to type every
letter of \forth{INITIALIZE} or \forth{TERMINAL} or \forth{BUFFER}.
These are the words you mean.
%Page 166 in first edition.

The worst problem with abbreviating a word is that you forget just
how you abbreviated it.  Was that \forth{DSPL} or \forth{DSPLY?}

Another problem is that abbreviations hinder readability.
Any programming language is hard enough to read without compounding
the difficulty.

Still, there are exceptions.  Here are a few:

\begin{enumerate}
\item Words that you use extremely frequently in code. \Forth{}
employs a handful of commands that get used over and over, but have
little or no intrinsic meaning:
\begin{Code}
:   ;   @   !   .   ,
\end{Code}
But there are so few of them, and they're used so often, they become
old friends.  I would never want to type, on a regular basis,
\begin{Code}
DEFINE   END-DEFINITION   FETCH   STORE
     PRINT   COMPILE#
\end{Code}
(Interestingly, most of these symbols don't have English counterparts.
We use the phrase ``\emph{colon} definition'' because there's no other
term; we say ``\emph{comma} a number into the dictionary'' because
it's not exactly compiling, and there's no other term.)
\item Words that a terminal operator might use frequently to control
an operation.  These words should be spelled as single letters, as are
line editor commands.
\item Words in which familiar usage implies that they be abbreviated.
\Forth{} assembler mnemonics are typically patterned after the
manufacturer's suggested mnemonics, which are abbreviations (such as
\forth{JMP} and \forth{MOV}).
\end{enumerate}%
\index{S!Spelled-out names|)}
Your names should be pronounceable; otherwise you may regret it when
you try to discuss the program with other people.  If the name is
symbolic, invent a pronunciation (e.g., \forth{>R} is called ``to-r'';
\forth{R>} is called ``r-from'').

\begin{tip}
Favor short words.
\end{tip}
Given the choice between a three-syllable word and a one-syllable word
that means the same thing, choose the shorter.  \forth{BRIGHT} is a
better name than \forth{INTENSE}.  \forth{ENABLE} is a better name
than \forth{ACTIVATE}; \forth{GO}, \forth{RUN}, or \forth{ON} may be
better still.

Shorter names are easier to type.  They save space in the source
screen.  Most important, they make your code crisp and clean.

\index{H!Hyphenated names|(}%
\begin{tip}
Hyphenated names may be a sign of bad factoring.
\end{tip}%
\index{A!Abbreviations|)}
%Page 168 in first edition.

\begin{interview}
\person{Moore}:\index{M!Moore, Charles|(}

\begin{tfquot}
There are diverging programming styles in the \Forth{} community.  One
uses hyphenated words that express in English what the word is doing.
You string these big long words together and you get something that is
quite readable.

But I immediately suspect that the programmer didn't think out the words
carefully enough, that the hyphen should be broken and the words defined
separately.  That isn't always possible, and it isn't always advantageous.
But I suspect a hyphenated word of mixing two concepts.%
\end{tfquot}\index{M!Moore, Charles|)}
\end{interview}
Compare the following two strategies for saying the same thing:
\begin{Code}
enable-left-motor        left motor on
enable-right-motor       right motor on
disable-left-motor       left motor off
disable-right-motor      right motor off
enable-left-solenoid     left solenoid on
enable-right-solenoid    right solenoid on
disable-left-solenoid    left solenoid off
disable-right-solenoid   right solenoid off
\end{Code}
The syntax on the left requires eight dictionary entries; the syntax
on the right requires only six-and some of the words are likely to be
reused in other parts of the application.  If you had a \forth{MIDDLE}
motor and solenoid as well, you'd need only seven words to describe
sixteen combinations.%
\index{H!Hyphenated names|)}

\begin{tip}
Don't bundle numbers into names.
\end{tip}
Watch out for a series of names beginning or ending with numbers, such
as \forth{1CHANNEL}, \forth{2CHANNEL}, \forth{3CHANNEL}, etc.

\index{B!Bundling of names and numbers|(}%
This bundling of names and numbers may be an indication of bad
factoring.  The crime is similar to hyphenation, except that what
should be factored out is a number, not a word.  A better factoring of
the above would be
\begin{Code}
1 channel
2 channel
3 channel
\end{Code}
In this case, the three words were reduced to one.

Often the bundling of names and numbers indicates fuzzy naming.
%Page 168 in first edition.
In the above case, more descriptive names might indicate the purpose
of the channels, as in
\begin{Code}
voice , telemetry , guitar
\end{Code}
%% Note: AH: the commas be better left out here.
\index{B!Bundling of names and numbers|)}%
We'll amplify on these ideas in the next chapter on ``Factoring.''%
\index{N!Names:!choosing|)}

\section{Naming Standards: The Science}%
\index{N!Naming conventions|(}

\begin{tip}
Learn and adopt \Forth{}'s naming conventions.
\end{tip}
In the quest for short, yet meaningful names, \Forth{} programmers
have adopted certain naming conventions.  \App{E} includes a list of
the most useful conventions developed over the years.

An example of the power of naming conventions is the use of ``dot''
to mean ``print'' or ``display.'' \Forth{} itself uses
\begin{Code}
.   d.   u.r
\end{Code}
for displaying various types of numbers in various formats.  The
convention extends to application words as well.  If you have a
variable called \forth{DATE,} and you want a word that displays the
date, use the name
\begin{Code}
.date
\end{Code}
\index{S!Suffixes|(}%
\index{P!Prefixes|(}%
A caution: The overuse of prefixes and suffixes makes words uglier and
ultimately less readable.  Don't try to describe everything a word
does by its name alone.  After all, a name is a symbol, not a
shorthand for code.  Which is more readable and natural sounding?:

\begin{tfquot}
Oedipus complex
\end{tfquot}
(which bears no intrinsic meaning), or
\begin{tfquot}
subconscious-attachment-to-parent-of-opposite-sex complex
\end{tfquot}
Probably the former, even though it assumes you know the play.

\begin{tip}
Use prefixes and suffices to differentiate between like words rather
than to cram details of meaning into the name itself.
\end{tip}
%Page 169 in first edition.
For instance, the phrase
\begin{Code}
... done IF close THEN ...
\end{Code}
is just as readable as
\begin{Code}
... done? IF close THEN ...
\end{Code}
and cleaner as well.  It is therefore preferable, unless we need an
additional word called \forth{DONE} (as a flag, for instance).

\medbreak
A final tip on naming:\index{W!Words:!choosing names|)}
\begin{tip}
Begin all hex numbers with ``0'' (zero) to avoid potential collisions
with names.
\end{tip}
For example, write \forth{0ADD}, not \forth{ADD}.%
\index{S!Suffixes|)}%
\index{P!Prefixes|)}

By the way, don't expect your \Forth{} system to necessarily conform
to the above conventions.  The conventions are meant to be used in
new applications.

\Forth{} was created and refined over many years by people who used it
as a means to an end.  At that time, it was neither reasonable nor
possible to impose naming standards on a tool that was still growing
and evolving.

Had \Forth{} been designed by committee, we would not love it so.%
\index{N!Naming conventions|)}%
\index{I!Implementation!choosing names|)}

\section{More Tips for Readability}

Here are some final suggestions to make your code more readable.
(Definitions appear in \App{C}.)

One constant that pays for itself in most applications is
\forth{BL}\index{B!Blank space (BL)}
(the ASCII value for ``blank-space'').

The word \forthb{[CHAR]} is used primarily within colon definitions to
free you from having to know the literal value of a character.  For
instance, instead of writing:
\begin{Code}
: (    41 word  drop ;  immediate
\end{Code}
where 41 is the ASCII representation for right-parenthesis, you can
write
\begin{Code}
: (    [char] ) word  drop ;  immediate
\end{Code}
\index{T!TRUE|(}%
\index{F!FALSE|(}%
A pair of words that can make dealing with booleans more readable are
\forthb{TRUE} and \forthb{FALSE}.  With these additions you can write
phrases such as

%Page 170 in first edition.
\begin{Code}
true 'stamp? !
\end{Code}
to set a flag or
\begin{Code}
false 'stamp? !
\end{Code}
to clear it.

(I once used \forthb{T} and \forthb{F}, but the words are
needed so rarely I now heed the injunction against abbreviations.)

As part of your application (not necessarily part of your \Forth{}
system), you can take this idea a step further and define:
\begin{Code}
: on   ( a)  true swap ! ;
: off   ( a)  false swap ! ;
\end{Code}
\index{T!TRUE|)}\index{F!FALSE|)}\index{O!ON}\index{O!OFF}%
These words allow you to write:
\begin{Code}
'stamp? on
\end{Code}
or
\begin{Code}
'stamp? off
\end{Code}
Other names for these definitions include \forth{SET} and
\forth{RESET}, although \forth{SET} and \forth{RESET} most commonly
use bit masks to manipulate individual bits.

An often-used word is \forthb{WITHIN},\index{W!WITHIN} which determines
whether a given value lies within two other values.  The syntax is:
\begin{Code}
n  lo hi within
\end{Code}
where ``n'' is the value to be tested and ``lo'' and ``hi'' represent
the range. \forthb{WITHIN} returns true if ``n'' is
\emph{greater-than or equal-to} ``lo'' and \emph{less-than}
``hi.'' This use of the non-inclusive upper limit parallels the syntax
of \forthb{DO }\forthb{LOOP}s.

\person{Moore}\index{M!Moore, Charles} recommends the word \forthb{UNDER+}.
It's useful for adding a value to the number just under the top stack
item, instead of to the top stack item.  It could be implemented in
high level as:
\begin{Code}
: under+  ( a b c -- a+c b )  rot +  swap ;
\end{Code}

\section{Summary}
Maintainability requires readability.  In this chapter we've enumerated
various ways to make a source listing more readable.  We've assumed a
%Page 171 in first edition.
policy of making our code as self-documenting as possible.  Techniques
include listing organization, spacing and indenting, commenting, name
choices, and special words that enhance clarity.

We've mentioned only briefly auxiliary documentation, which includes
all documentation apart from the listing itself.  We won't discuss
auxiliary documentation further in this volume, but it remains an
integral part of the software development process.%
\index{I!Implementation|)}

\begin{references}{9}
\bibitem{stevenson81} \person{Gregory Stevenson}, ``Documentation Priorities,''
\emph{1981 FORML Conference Proceedings,} p. 401.
\bibitem{lee81} \person{Joanne Lee}, ``Quality Assurance in a \Forth{}
Environment,'' (Appendix A), \emph{1981 FORML Proceedings,} p. 363.
\bibitem{dijkstra82} \person{Edsger W. Dijkstra}, \emph{Selected Writings on
Computing: A Personal Perspective,} New York, Springer Verlag, Inc.,
1982.
\bibitem{laxen} \person{Henry Laxen}, ``Choosing Names,'' \emph{\Forth{} Dimensions,}
vol. 4, no.\ 4, \Forth{} Interest Group.
\end{references}

%Page 172 in first edition.