The occam-pi Style Guide

Introduction

While occam-pi is a reasonably style-constrained language, examining existing code suggests that there's still some scope for style variation. This page attempts to document best practices for occam-pi programmers, largely based on the style used in the course examples and library.

Source files

All indentation should be done using spaces; tab characters shouldn't appear in occam-pi source. (All decent text editors can be set up to automatically expand tabs to spaces, and since you'll want two-space indentation you've probably done this already.)

As occam-pi's handling of non-US-ASCII characters in source files is currently undefined, source files should only contain the US-ASCII character set (that is, Unicode code points U+0001 to U+007F, encoded in single bytes).

Source files for programs (that is, source files that contain a top-level process) should be named the same as the top-level process, with . replaced by _; the binary generated from them will usually be called the same thing.

Avoid excessively long lines in source files. For ease of reading and printing source files, it is usually a good idea to break lines longer than 80 characters. Indent continuation lines in PROC headers by four spaces, and in PROTOCOLs by two spaces. For example:

PROC with.lots.of.args (VAL INT first, second, third,
    BYTE fourth, fifth, sixth,
    RESULT BOOL seventh)
  ...  body
:
PROTOCOL WITH.LOTS.OF.ITEMS IS
  INT;
  BYTE;
  BOOL:

Identifiers

PROCs, FUNCTIONs and variables should be named using lower-case characters and numbers, with words separated by dots.

Data types, protocols and constant values should be named using upper-case characters and numbers, with words separated by dots.

Mixed-case names aren't currently used for anything.

Exceptions to this rule are common when the occam-pi code is actually wrapping an existing API from another language (for example, filelib's wrappers for POSIX functions and constants, or the OpenGL bindings); in that case, it's less awkward to keep the existing names (replacing underscores with dots).

Spacing

Put a single space between a PROC or FUNCTION name and its arguments, and between its arguments. Elide repeated types.

In expressions, put spaces around operators, but not around or inside brackets:

Similarly with input/output processes:

Do not put spaces around array dimensions:

Or before colons:

Put spaces after (but not before) semicolons in protocols:

Put spaces before type decorations:

Parameters

Use direction specifiers wherever possible (including places where it doesn't matter) -- the idea is that using the direction specifier indicates that you only have one end of the channel (or set of channels) available:

Use VAL and RESULT to mark input and output parameters.

Deprecated syntax

For channels and placed items, elide the optional OF and AT keywords:

For abbreviations, always specify the type:

Top-level process

Use the new CHAN BYTE interface rather than the old SP libraries. Use the full standard names for the channels, and elide those that you aren't using (the compiler can tell from the names which you want):

Preprocessor directives

Align #IF directives (etc.) horizontally with the code they protect.

Elide .tce from #USE directives where possible:

Avoid keeping dead code in files (it's better to put the file under version control, then remove the code); if you must do so, then wrap it in #IF FALSE ... #ENDIF rather than commenting out every line.

Folds

Always put two spaces between a start-of-fold marker and the fold name. Don't put anything after an end-of-fold marker. Align folds horizontally with the code they're folding.

--{{{  fold name

--}}}

Put folds around all PROCs and FUNCTIONs, and include the full header on a single line in the fold name:

--{{{  PROC foo ([]BYTE a, VAL INT length)

Add discretionary folds around blocks of code that have a specific function, making the fold name start with a lower-case letter:

--{{{  name of the fold

When using discretionary folds inside an IF or ALT, wrap it around the process, not the condition.

Hide long chunks of comment text inside folds too:

--{{{  COMMENT documentation

Use OccamDoc for inline documentation.

Pseudocode

When writing pseudocode, write elided blocks as a name preceded by three dots and two spaces:

...  frobulate the prognosticator

Highlight pseudocode elements differently from real code.

OccamPiStyleGuide (last edited 2006-10-31 14:33:06 by ats1)