Forth Programmer’s Handbook

6.1 GUIDELINES FOR BLOCK-BASED SOURCE

The purpose of this section is to describe a set of standards used for editing block-based Forth source code, to ensure readability and notational consistency.

6.1.1 Stack Effects

1.Any colon or code definition which expects or leaves data stack arguments must include a comment identifying them.

2.The format of the comment is:

( input - output )

with the rightmost item on each side of the dash representing the top item on the stack. If there is input but no output, you may omit the dash.

3.The stack comment begins one space after the name of the word. The terminating parenthesis should follow the last character, without a space. Exactly three spaces follow the right parenthesis before the code begins, if it begins on the same line. Remember to leave one space after the opening (.

4.The specific notation used to represent each stack item should follow these conventions:

aaddress

beight-bit byte

cASCII character

n single-precision number, usually signed u single-precision unsigned number

t Boolean truth flag (0=false)

The following special cases should be used when appropriate:

l c Screen position, in lines and columns (always in that order). s d n Source, destination, count (always in that order).

y x 2-vector (x,y coordinate pairs, e.g., for graphics).

184 Programming Style

Forth Programmer’s Handbook

Other special situations may be dealt with similarly if necessary to improve clarity, but use single characters where possible.

5.Where several arguments are of the same type and clarity demands that they be distinguished, use ' (prime) or suffix numerals. For example:

CODE RSWAP ( n a a' - n a)

CODE RSWAP ( n a1 a2 - n a1)

both show that the address returned is the same as the first one input.

6.1.2 General Comments

1.All source files must start with a comment which succinctly describes their contents. Some examples of good and bad style follow:

2.Comments within source (other than stack effects) should be restricted to situations in which a serious ambiguity needs to be resolved.

good: 177566 ( Send +2) and 177562 ( RCV+2) redundant: DUP 0= ABORT" Value is zero" ( Aborts if zero) unhelpful: S ) 0 MOV ( Move top of stack to R0)

3.Comments should begin with a capital letter and otherwise be lower case, except as standard usage indicates, e.g.,

( Defining words) ( RX01 Bootstrap)

6.1.3 Spacing Within Source

1.Blank lines within source are valuable. Use them to separate definitions or groups of definitions. Avoid a dense clump of lines at the top of a file with a

Programming Style 185

Forth Programmer’s Handbook

lot of blank lines below, unless the clump is a single definition. Never have two blank lines together except at the end.

2.Definitions should begin in the left-most column of a line, except that two or three related VARIABLEs, CONSTANTs, or other data items may share a line if there is room for three spaces between them.

3.The name of a definition must be separated from its defining word by only one space. If it is a CONSTANT or other data item with a specified value, the value must be separated from the defining word by only one space.

4.Within a colon definition, three spaces are required after the stack comment. Thereafter, words are separated by one space, except when a second space is added between groups of closely related words.

5.Second and subsequent lines of colon and CODE definitions must be indented by multiples of three spaces (e.g., 3, 6, 9). Indentation beyond one set of three spaces indicates nested structures.

Examples of Forth in documentation should conform to these rules.

6.2OPEN FIRMWARE CODING STYLE

This section describes the coding style in some Open Firmware 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 Open Firmware work. This will make your code more easily understood by others within the Open Firmware community.

6.2.1 Typographic Conventions

The following typographic conventions are used in this document:

!The symbol _ is used to represent space characters (i.e., ASCII 0x20).

!The symbol … is used to represent an arbitrary amount of Forth code.

!Within prose descriptions, Forth words are shown in this font.

186 Programming Style

Forth Programmer’s Handbook

6.2.2 Use of Spaces

Since Forth code can be very terse, the judicious use of spaces can increase the readability of your code.

Two consecutive spaces are used to separate a definition’s name from the beginning of the stack diagram, another two consecutive spaces (or a new line) are used to separate the stack diagram from the word’s definition, and two consecutive spaces (or a new line) 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 new line.

: name__(_stack before_--_stack after_)__xxx_xxx__xxx_xxx__;

When creating multiple line definitions, all lines except the first and last should be indented by three (3) spaces. If additional indention 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) __xxx…

____xxx…

____xxx… __xxx…

6.2.3 Conditional Structures

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__xxx__then__ __if__xxx__else__xxx__then__

Programming Style 187