REBOL 3 Docs Guide Concepts Functions Datatypes Errors
  TOC < Back Next >   Updated: 6-Feb-2009 Edit History  

REBOL 3 Concepts: Scripts: Style Guide

Pending Revision

This document was written for R2 and has yet to be revised for R3.

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.

Indent Content 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

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"

Standard Tab Size

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.

Detab Before Posting

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

Limit Line Lengths to 80 Characters

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.

Word Names

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.

Use the Shortest Word that Communicates the Meaning

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.

Use Whole Words Where Possible

What you save when abbreviating a word is rarely worth it. Type date not dt, or image-file not imgfl.

Hyphenate Multiple Word Names

The standard style is to use hyphens, not character case, to distinguish words.

group-name image-file  clear-screen  bake-cake

Begin Function Names with a Verb

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?

Begin Data Words with Nouns

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

Use Standard Names

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

Script Headers

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.

    Title: "Local Area Defringer"
    Date:  1-Jun-1957
    File:  %defringe.r
    Purpose: {
        Stabilize the wide area ignition transcriber
        using a double ganged defringing algorithm.

Function Headers

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"

Script File Names

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.


Embedded Examples

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.

Embedded Debugging

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

Minimize Globals

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 > - WIP Wiki Feedback Admin