| REBOL 3 Docs | Guide | Concepts | Functions | Datatypes | Errors |
| TOC < Back Next > | Updated: 6-Feb-2009 Edit History |
REBOL scripts are free-form. You can write a script using the indenting, spacing, line length, and line terminators you prefer. You can put each word on a separate line or join them together on one long line.
While the formatting of your script does not affect the interpreter, it does affect its human readability. Because of this, REBOL Technologies encourages you to follow the standard scripting style described in this section.
Of course, you don't have to follow any of these suggestions. However, scripting style is more important than it first seems. It can make a big difference in the readability and reuse of scripts. Users may judge the quality of your scripts by the clarity of their style. Sloppy scripts often mean sloppy code. Experienced script writers usually find that a clean, consistent style makes their code easier to produce, maintain, and revise.
Use the following guidelines for formatting REBOL scripts for clarity.
The contents of a block are indented, but the block's enclosing square brackets [ ] are not. That's because the square brackets belong to the prior level of syntax, as they define the block but are not contents of the block. Also, it's easier to spot breaks between adjacent blocks when the brackets stand out.
Where possible, an opening square bracket remains on the line with its associated expression. The closing bracket can be followed by more expressions of that same level. These same rules apply equally to parenthesis ( ) and braces { }.
if check [do this and that]
if check [
do this and do that
do another thing
do a few more things
]
either check [do something short][
do something else]
either check [
when an expression extends
past the end of a block...
][
this helps keep things
straight
]
while [
do a longer expression
to see if it's true
][
the end of the last block
and start of the new one
are at the WHILE level
]
adder: func [
"This is an example function"
arg1 "this is the first arg"
arg2 "this is the second arg"
][
arg1 + arg2
]
An exception is made for expressions that normally belong on a single line, but extend to multiple lines:
if (this is a long conditional expression that
breaks over a line and is indented
)[
so this looks a bit odd
]
This also applies to grouped values that belong together, but must be wrapped to fit on the line:
[
"Hitachi Precision Focus" $1000 10-Jul-1999
"Computers Are Us"
"Nuform Natural Keyboard" $70 20-Jul-1999
"The Keyboard Store"
]
REBOL standard tab size is four spaces. Because people use different editors and readers for scripts, you can elect to use spaces rather than tabs.
The tab character (ASCII 9) does not indent four spaces in many viewers, browsers, or shells, so use an editor or REBOL to detab a script before publishing it to the net. The following function detabs a file with standard four-space tabs:
detab-file: func [file-name [file!]] [
write file-name detab read file-name
]
detab-file %script.r
The following function converts an eight-space tabs to four-space tabs:
detab-file: func [file-name [file!]] [
write file-name detab entab/size read file-name 8
]
For ease of reading and portability among editors and email readers, limit lines to 80 characters. Long lines that get wrapped in the wrong places by email clients are difficult to read and have problems loading.
Words are a user's first exposure to your code, so it is critical to choose words carefully. A script should be clear and concise. When possible, the words should relate to their English or other human language equivalent, in a simple, direct way.
The following are standard naming conventions for REBOL.
Short, crisp words work best where possible:
size time send wait make quit
Local words can often be shortened to a single word. Longer, more descriptive words are better for global words.
What you save when abbreviating a word is rarely worth it. Type date not dt, or image-file not imgfl.
The standard style is to use hyphens, not character case, to distinguish words.
group-name image-file clear-screen bake-cake
Function names begin with a verb and are followed by a noun, adverb, or adjective. Some nouns can also be used as verbs.
make print scan find show hide take rake-coals find-age clear-screen
Avoid unnecessary words. For instance, quit is just as clear as quit-system.
When using a noun as a verb, use special characters such as ? where applicable. For instance, the function for getting the length of a series is length?. Other REBOL functions using this naming convention are:
size? dir? time? modified?
Words for objects or variables that hold data should begin with a noun. They can include modifiers (adjectives) as needed:
image sound big-file image-files start-time
There are standard names in REBOL that should be used for similar types of operations. For instance:
make-blub ;creating something new free-blub ;releasing resources of something copy-blub ;copying the contents of something to-blub ;converting to it insert-blub ;inserting something remove-blub ;removing something clear-blub ;clearing something
The advantage of using headers is clear. Headers give users a summary of a script and allow other scripts to process the information (like a cataloging script). A minimum header provides a title, date, file name and purpose. Other fields can also be provided such as author, notes, usage, and needs.
REBOL [
Title: "Local Area Defringer"
Date: 1-Jun-1957
File: %defringe.r
Purpose: {
Stabilize the wide area ignition transcriber
using a double ganged defringing algorithm.
}
]
It is useful to provide a description in function specification blocks. Limit such text to one line of 70 characters or less. Within the description, mention what type of value the function normally returns.
defringe: func [
"Return the defringed localization radius."
area "Topo area to defringe"
time "Time allotted for operation"
/cost num "Maximum cost permitted"
/compound "Compound the calculation"
][
...code...
]
The best way to name a file is to think about how you can best find that file in a few months. Short and clear names are often enough. Plurals should be avoided, unless meaningful.
In addition, when naming a script, consider how the name will sort in a directory. For instance, keep related files together by starting them with a common word.
%net-start.r %net-stop.r %net-run.r
Where appropriate, provide examples within a script to show how the script operates and to give users a quick way of verifying that the script works correctly on their system.
It is often useful to build in debugging functions as part of the script. This is especially true of networking and file handling scripts where it is not desirable to send and write files while running in test mode. Such tests can be enabled with a control variable at the head of the script.
verbose: on check-data: off
In large scripts and where possible, avoid using global variables that carry their internal state from one module or function to another. For short scripts, this isn't always practical. But recognize that short scripts may become longer scripts over time.
If you have a collection of global variables that are closely related, consider using an object to keep track of them:
user: make object! [
name: "Fred Dref"
age: 94
phone: 707-555-1234
email: dref@fred.dom
]
| TOC < Back Next > | REBOL.com - WIP Wiki | Feedback Admin |