This appendix describes the coding style used in some OpenBoot implementations. These guidelines are a living document that first came into existence in 1985. By following these guidelines in your own code development, you will produce code that is similar in style to a large body of existing OpenBoot work. This will make your code more easily understood by others in the OpenBoot community.
The following typographic conventions are used in this document:
Since Forth code can be very terse, use spaces to increase readability.
Two consecutive spaces are used to separate a definition's name from the beginning of the stack diagram, another two consecutive spaces (or a newline) are used to separate the stack diagram from the word's definition, and two consecutive spaces (or a newline) separate the last word of a definition from the closing semi-colon. For example:
: new-name<<(<stack-before<--<stack-after<)<<foo<<bar<<;
: new-name<<(<stack-before<--<stack-after<)
<<<foo<bar<framus<dup<widget<foozle<ribbit<grindle
;
Forth words are usually separated by one space. If a phrase consisting of several words performs some function, that phrase should be separated from other words/phrases by two consecutive spaces or a newline.
: name<<(<stack before<--<stack after<)<<qqq<yyy<<ggg<ppp<<;
When creating multiple line definitions, all lines except the first and last should be indented by three (3) spaces. If additional indentation is needed with control structures, the left margin of each additional level of indentation should start three (3) spaces to the right of the preceding level.
: name ( stack before -- stack after )
<<<qqq...
<<<<<<qqq...
<<<<<<qqq...
<<<qqq...
;
In if...then or if...else...then control structures that occupy no more than one line, two spaces should be used both before and after each if, else or then.
<<if<<qqq<<then<<
<<if<<qqq<<else<<ppp<<then<<
Longer constructs should be structured like this:
<code to generate flag'><<if
<<<<true clause'>
then
<code to generate flag'><<if
<<<<true clause'>
else
<<<<false clause'>
then
In do...loop constructs that occupy no more than one line, two spaces should be used both before and after each do or loop.
<code to calculate limits'><<do<<qqq<<loop<<
Longer constructs should be structured like this:
<code to calculate limits'><<do
<<<<body'>
loop
The longer +loop construct should be structured like this:
<code to calculate limits'><<do
<<<<body'>
<incremental value'><+loop
In begin...while...repeat constructs that occupy no more than one line, two spaces should be used both before and after each begin, while or repeat).
<<begin<<<flag code'><<while<<<body'><<repeat<<
Longer constructs:
begin<<<short flag code'><<while
<<<<body'>
repeat
begin
<<<<long flag code'>
while
<<<<body'>
repeat
In begin...until and begin...again constructs that occupy no more than one line, two spaces should be used both before and after each begin, until or again.
<<begin<<<body'><<until
<<begin<<<body'><<again
Longer constructs:
begin
<<<<body'>
until
begin
<<<<body'>
again
Block comments begin with \<. All text following the space is ignored until after the next newline. While it would be possible to delimit block comments with parentheses, the use of parentheses is reserved by convention for stack comments.
Precede each non-trivial definition with a block comment giving a clear and concise explanation of what the word does. Put more comments at the very beginning of the file to describe external words which could be used from the User Interface.
Stack comments begin with (< and end with ). Use stack comments liberally in definitions. Try to structure each definition so that, when you put stack comments at the end of each line, the stack picture makes a nice pattern.
: name ( stack before -- stack after )
<<<qqq ppp bar ( stack condition after the execution of bar )
<<<qqq ppp foo ( stack condition after the execution of foo )
<<<qqq ppp dup ( stack condition after the execution of dup )
;
Return stack comments are also delimited with parentheses. In addition, the notation r: is used at the beginning of the return stack comment to differentiate it from a parameter stack comment.
Place return stack comments on any line that contains one or more words that cause the return stack to change. (This limitation is a practical one; it is often difficult to do otherwise due to lack of space.) The words >r and r'> must be paired inside colon definitions and inside do...loop constructs.
: name ( stack before -- stack after )
<<<qqq r ( r: addr )
<<<qqq r'> ( r: )
;
Hexadecimal numbers should be typed in lower case. If a given number contains more than 4 digits, the number may be broken into groups of four digits with periods. For example:
dead.beef
Since the default number base is hexadecimal, the convention is not to precede hexadecimal numbers with h#.