retroforth/doc/book/techniques/naming-conventions

# Naming Conventions

Word names in RETRO generally follow the following conventions.

## General Guidelines

* Readability is important
* Be consistent
* Don't use a sigil as the first character of a name
* Don't use underscores in word names
* Use short names for indices
* Word names start with a `-` for "not"
* Words returning a flag end in ?

## Typical Format

The word names will generally follow a form like:

    [namespace:]name

The `namespace:` is optional, but recommended for consistency
with the rest of the system and to make it easier to identify
related words.

## Case

Word names are lowercase, with a dash (-) for compound names.

    hello
    drop-pair
    s:for-each

Variables use TitleCase, with no dash between compound names.

    Base
    Heap
    StringBuffers

Constants are UPPERCASE, with a dash (-) for compound names.

    TRUE
    FALSE
    f:PI
    MAX-STRING-LENGTH

## Namespaces

Words are grouped into broad namespaces by attaching a short
prefix string to the start of a name.

The common namespaces are:

    | Prefix  | Contains                                               |
    | ------- | ------------------------------------------------------ |
    | a:      | Words operating on simple arrays                       |
    | ASCII:  | ASCII character constants for control characters       |
    | buffer: | Words for operating on a simple linear LIFO buffer     |
    | c:      | Words for operating on ASCII character data            |
    | class:  | Contains class handlers for words                      |
    | d:      | Words operating on the Dictionary                      |
    | err:    | Words for handling errors                              |
    | io:     | General I/O words                                      |
    | n:      | Words operating on numeric data                        |
    | sigil:  | Contains sigil handlers                                |
    | s:      | Words operating on string data                         |
    | v:      | Words operating on variables                           |
    | file:   | File I/O words                                         |
    | f:      | Floating Point words                                   |
    | unix:   | Unix system call words                                 |

## Tips

### Don't Start Names With Sigil Characters

Avoid using a sigil as the first character of a word name. RETRO
will look for sigils first, this will prevent direct use of
the work in question.

To find a list of sigil characters, do:

    'sigil: d:words-with

### Don't Use Underscores

Underscores in strings are replaced by spaces. This is problematic,
especially with variables. Consider:

    'test_name var
    #188 !test_name

In this, the string for the name is converted to "test name". The
store in the second line will not add the space, so resolves to an
incorrect address.

I personally recommend avoiding the use of underscores in any word
names.