retroforth/doc/book/Programming-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 prefix 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                        |
| prefix: | Contains prefix handlers                               |
| s:      | Words operating on string data                         |
| v:      | Words operating on variables                           |
| file:   | File I/O words                                         |
| f:      | Floating Point words                                   |
| gopher: | Gopher protocol words                                  |
| unix:   | Unix system call words                                 |

## Tips

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

To find a list of prefix characters, do:

```
'prefix: d:words-with
```

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.