| Writing FCode 3.x Programs |    
|
| Writing FCode 3.x Programs |
|
| A P P E N D I X C |
|
Forth Coding Style |
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.
This document contains the following sections:
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 semicolon. 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, separate the phrase from other words or phrases by two consecutive spaces or a newline.
: name<<(<stack before<--<stack after<)<<qqq<yyy<<ggg<ppp<<;
When creating multiple line definitions, indent all lines except the first and last by three (3) spaces. If additional indentation is needed with control structures, start the left margin of each additional level of indentation 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, use two spaces both before and after each if, else or then.
<<if<<qqq<<then<<
<<if<<qqq<<else<<ppp<<then<<
Structure longer constructs 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, use two spaces both before and after each do or loop.
<code to calculate limits><<do<<qqq<<loop<<
Structure longer constructs like this:
<code to calculate limits><<do
<<<<body>
loop
Structure the longer +loop construct like this:
<code to calculate limits><<do
<<<<body>
<incremental value><+loop
In begin...while...repeat constructs that occupy no more than one line, use two spaces both before and after each begin, while, or repeat.
<<begin<<<flag code><<while<<<body><<repeat<<
Structure longer constructs like this:
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, use two spaces both before and after each begin, until or again.
<<begin<<<body><<until
<<begin<<<body><<again
Structure longer constructs like this:
begin
<<<<body>
until
begin
<<<<body>
again
Block comments begin with \<. All text following the space is ignored until after the next newline. The use of parentheses is reserved by convention for stack comments.
Precede each nontrivial 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: )
;
Type hexadecimal numbers in lowercase. If a given number contains more than four 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#.
| Writing FCode 3.x Programs | 806-1379-10 |
|
Copyright © 2004, Sun Microsystems, Inc. All Rights Reserved.