Style Guide

PForth Style Guide

This guide is a work in progress. I welcome input from other developers.

Goals

• Consistent style for new additions. When the style is settled I may apply it to old code.
• Consistent with older projects, specifically HMSL.
• Improve readability.

Both Forth and 'C'

Indentation - 4 spaces, no tabs, no trailing spaces

Exemptions - external code, such as the t_*.fth test files, should keep their original formatting.

Forth

Letter Case

• Use upper case for new words when they are defined.
• Use upper case for words that control execution flow, including:
• IF ELSE THEN EXIT
• DO LOOP
• CASE OF ENDOF ENDCASE
• BEGIN UNTIL WHILE REPEAT
• CREATE DOES>
• Use lower case for other words, eg. dup swap etc.
• Forth words in comments should be upper case.

Alignment

• Align conditional words, for example IF and THEN, on the same column.
• Very short IF THEN conditionals can be on one line.
• Semicolons for definitions that span multiple lines should be in column one. One line short definitions are OK.
• Comments should be aligned with the code.

For example:

: NEW.WORD ( x y -- , do something interesting without using SWAP )
    2dup =
    \ Note comment aligned with code.
    IF +
    ELSE *
    THEN
;
: DOOP ( n -- n n , one liner ) dup ;

Special Characters

• Avoid excessive use of punctuation characters.
• Words that obtain a value can end in '@', eg. SP@
• Words that store a value can end in '!', eg. SP!
• Words that print can start with '.', eg. .HEX
• Words that accept a counted string can begin with '$', eg. $TYPE ( $text -- )
• Constants should use underscores as separators, eg. MIDI_NUM_PORTS
• Words can use '.' or '-' as separators, eg. AUTO.INIT or SAVE-FORTH
• Words that translate can use '>', eg. S>F

'C'