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) or 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 is using a different style for arrays and structures. Direction, Conversion backwards name< SLIDE< forwards name< CMOVE< from 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 #> 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.