Summary of Forth Style Conventions

This is a Forth Style guide for Forth-83 placed in the public domain by Leo Brodie

Spacing and Indentation Guidelines

  • 1 space between the colon and the name
  • 2 spaces between the name and the comment *
  • 2 spaces, or a carriage return, after the comment and before the definition *
  • 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 with a phrase
  • 2 or 3 spaces between phrases
  • 1 space between the last word and the semicolon
  • 1 space between the semicolon and IMMEDIATE (if invoked)

No blank lines between definitions, except to separate distinct groups of defintions

* An often seen-alternative calls for 1 more space between the name and comment and 3 between the comment and the defintion. A more liberal technique uses 3 spaces before and after teh comment. Whatever you choose, be consistent.

Stack-Comment abbreviations

     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 :
     t=           true
     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)

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.

Input-Stream Comment Designations

     c             single character, blank delimited
     name          sequence of characters, blank delimited
     text          sequence of characters, delimited by nonblank

Follow "text" with the actual delimiter required, e.g., text" or text).

Samples of Good Commenting Style

Here are two sample screens to illustrate good commenting style. 


Screen #126
 0 \ Formatter          Data Structures -- p.2    06/06/83
 1  6 CONSTANT TMARGIN  \ line# where body of text begins
 2 55 CONSTANT BMARGIN  \ line# where body of text ends
 3
 4 CREATE HEADER  82 ALLOT
 5   ( 1left-cnt | 1right-cnt | 80header )
 6 CREATE FOOTER  82 ALLOT
 7   ( 1left-cnt | 1right-cnt | 80footer )
 8
 9 VARIABLE ACROSS   \ formatter's current horizontal position
10 VARIABLE DOWNWARD \ formatter's current vertical position
11 VARIABLE LEFT     \ current primary left margin
12 VARIABLE WALL     \ current primary right margin
13 VARIABLE WALL-WAS \ WALL when curr. line started being formatted
14
15

Screen #127
 0 \ Formatter          positioning -- p.1        06/06/83
 1 : SKIP  ( n -- )  ACROSS +! ;
 2 : NEWLEFT      \ reset left margin
 3    LEFT @  PERMANENT @ + TEMPORARY @ + ACROSS ! ;
 4 : \LINE        \ begin new line
 5    DOOR CR'   1 DOWNWARD +!  NEWLEFT  WALL @ WALL-WAS ! ;
 6 : AT-TO{? ( -- t=at-top )   TMARGIN DOWNWARD @ = ;
 7 : >TMARGIN     \ move from crease to TMARGIN
 8      0 DOWNWARD !  BEGIN \LINE  AT-TOP? UNTIL ;
 9
10
11
12
13
14
15

Naming Conventions

Meaning Form Example
 
Arithmetic
integer 1 1name 1+
integer 2 2name 2*
takes relative input parameters +name +DRAW
takes scaled input parameters *name *DRAW
 
Compilation
start of "high level" code name: CASE:
end of "high level" code ;name ;CODE
put something into dictionary name, C,
executes at compile time [name] [COMPILE]
(slightly different) name' (prime) CR'
internal form or primitive (name) (TYPE)
<name> <TYPE>
compiling word run-time part:
systems with no folding lower-case if
systems with folding (NAME) (IF)
defining word :name :COLOR
block-number where overlay begins namING DISKING
 
Data Structures
table or array names EMPLOYEES
total number of elements #name #EMPLOYEES
current item number (variable) name# EMPLOYEE#
sets current item ( n )name 13 EMPLOYEE
advance to next element +name +EMPLOYEE
size of offset to item from name+ DATE+
beginning of structure
size of (bytes per) /name /EMPLOYEE
(short for BYTES/name)
index pointer >name >IN
convert address of structure to >name >BODY
address of item
file index (name) (PEOPLE)
file pointer -name -JOB
initialize structure 0name 0RECORD
Note: The Forth Scientific Library uses a different style for arrays and structures.
 
Direction, Conversion
backwards name< SLIDE<
forwards name< CMOVE<
from <name <TAPE
to >name >TAPE
convert to name>name FEET>METERS
downward \name \LINE
upward /name /LINE
open {name {FILE
close }name FILE}
 
Logic, Control
return boolean value name? SHORT?
returns reversed boolean value -name? -SHORT?
address of boolean 'name? 'SHORT?
operates conditionally ?name ?DUP
(maybe DUP)
enable +name +CLOCK
or, absence of symbol name BLINKING
disable -name -CLOCK
-BLINKING
 
Memory
save value of (to stack) @name @CURSOR
restore value of !name !CURSOR
store into name! SECONDS!
fetch from name@ INDEX@
name of buffer :name :INSERT
address of name 'name 'S
address of pointer to name 'name 'TYPE
exchange, especially bytes >name< >MOVE<
 
Numeric Types
byte length Cname C@
2 cell size, 2's complement Dname D@
integer encoding
mixed 16 and 32-bit operator Mname M*
3 cell size Tname T*
4 cell size Qname Q*
unsigned encoding Uname U.
 
Output, Printing
print item .name .S
print numeric name. D. U.
(name denotes type)
print right justified name .R U.R
 
Quantity
"per" /name /SIDE
 
Sequencing
start <name <#
end name> #>
 
Text
string follows delimited by " name" ABORT" text"
text or string operator "name "COMPARE
(similar to $ prefix in BASIC)
superstring array "name" "COLORS"

How to pronounce the Symbols

     !          store
     @          fetch
     #          sharp ( or "number" as in #RECORDS)
     $          dollar
     %          percent
     ^          caret
     &          ampersand
     *          star
     (          left paren; paren
     )          right paren; paren
     -          dash; not
     +          plus
     =          equals
     { }        faces (traditionally called "curly brackets")
     [ ]        square brackets
     "          quote
     '          as prefix: tick; as suffix: prime
     ~          tilde
     |          bar
     \          backslash (also "under", "down" and "skip")
     /          slash (also "up")
     <          less than
                left dart
     >          greater than
                right dart
     ?          question (some prefer "query")
     ,          comma
     .          dot

Source: Brodie, Leo, 1984; Thinking Forth, A Language and a Philosophy for Solving Problems, Prentice-Hall, Englewood Cliffs, N.J., 300 pages. ISBN 0-13-917568-7

This book has been out of print, and is now being republished by the Forth Interest Group.