96 lines
2.9 KiB
Text
96 lines
2.9 KiB
Text
# 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.
|