Octave style guide

A lot of GNU Octave is written in the Octave language itself. This document details the Octave style used by the GNU Octave project.

Being part of the GNU project, Octave inherits the GNU coding standards. However, those were written with C in mind and can't always apply to Octave code.

See also the GNU Octave C++ style guide.

Formatting

Line Length

Keep the length of source lines to 79 characters or less, for maximum readability in the widest range of environments. This is inherited from the GNU Coding Standards.

Indentation

Use only spaces, and indent 2 spaces at a time.

We use spaces for indentation. Absolutely do not use tabs in your code. You should probably set your editor to emit spaces when you hit the tab key.

Whitespace

When calling functions, put spaces after commas and before the calling parentheses, like this:

x = max (sin (y+3), 2);

An exception are matrix or cell constructors:

[sin(x), cos(x)]
{sin(x), cos(x)}

Here, putting spaces after sin, cos would result in a parse error.

For indexing expressions, do not put a space after the identifier (this differentiates indexing and function calls nicely). The space after a comma is not necessary if index expressions are simple, i.e., you may write

A(:,i,j)

but

A([1:i-1;i+1:n], XI(:,2:n-1))

When constructing matrices, prefer using the comma rather than the space to distinguish between columns.

  M = [1, 2, 3
       4, 5, 6];

However, if the matrix is large or the indentation makes it clear the comma may be dropped.

  prices = [ 1.01  2.02  3.03
            44.04 55.05  6.06];

Error messages

When you encounter an error condition, call the function error (or print_usage). The error and print_usage functions do not return. It is customary to prefix the error message with the name of the function that generated it. For example:

error ("my_cool_function: input A must be a matrix");

Octave has several functions that produce error messages according to the Octave guidelines. Consider using inputParser and validateattributes.

Naming

Use lowercase names if possible. Uppercase is acceptable for variable names consisting of 1-2 letters. Do not use mixed case names. Function names must be lowercase. Function names are global, so choose them wisely.

Function names

For most public functions we are limited by Matlab compatibility. Use whatever name Matlab choose.

For functions that are not present in Matlab favour the use of underscores. For example, base64_decode, common_size, or compare_versions. There are exceptions to this:

Matching C functions

If the function exists elsewhere with a common name, use it. For example, dup2, waitpid, printf, argv, or getopt.

Matching similar functions

If there are similarly named functions, consider using same style. For example, fftconvn and histthresh, match the naming of fftconv2 and graythresh.

ending blocks

Always use a specific end-of-block statement (like endif, endswitch) rather than the generic end.

Enclose the condition of an if, while, until, or switch statement in parentheses, as in C:

if (isvector (a))
  s = sum (a);
endif

Do not do this, however, with the iteration counter portion of a for statement. Write:

for i = 1:n
  b(i) = sum (a(:,i));
endfor

! operator

The Octave operator ! should be used for logical negation, rather than ~. The negation operator is written with a space between the operator and its target, e.g., ! A.

Comments

# or %

Always use # to write comments.

Absolutely do not use %# or mix % and # in the same file.

Block and Inline comment

Use a single # for inline comments. Use double ## for block comments.

Comments that start with a single sharp-sign, #, are used to explain the code on the same line as the comment itself. These comments should all be aligned to the same column to the right of the source code. In the Emacs mode for Octave, the M-; (@code{indent-for-comment}) command automatically inserts such a # in the right place, or aligns such a comment if it is already present. Example:

C = 2 * pi * r;    # formula for circumference of a circle

Comments that start with a double sharp-sign, ##, are stand-alone comments that occupy an entire line. These comments should be aligned to the same level of indentation as the code. Such comments usually describe the purpose of the following lines or the state of the program at that point. Example:

## Calculate area and volume of a sphere
A = 4 * pi * r^2;
V = 4/3 * pi * r^3;

Commenting out code

Do not comment code out. If the code is no longer used, remove it. We use version control, we can always bring it back.

%! for test and demo blocks

Any demos or Built-In Self Tests (BIST) using the %!demo or %!test syntax should begin two lines after the endfunction keyword. Demo blocks should be listed before test blocks.

See the section Writing tests on the Tests page.

FIXME notes

The preferred comment mark for places that may need further attention is with FIXME: comments.