retroforth/doc/book/techniques/naming-conventions
crc b2ac237c35 update documentation
FossilOrigin-Name: 61bec5c3ab74da3be2fa090a346b667bfa03cea534d8b378b9ac3245412bdc72
2020-01-07 14:09:08 +00:00

101 lines
2.8 KiB
Text

# 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.