Code Conventions for the Scilab Programming Language

Contents

Code Conventions for the Scilab Programming Language

Functions

names

Scilab has not a good record of consistent naming.

All names should be written in English
Function names may only contain alphanumeric characters. Underscores are not permitted. Numbers are permitted in function names but are discouraged in most cases.
Function names must always start with a lowercase letter. When a function name consists of more than one word, the first letter of each new word must be capitalized.
Verbosity is generally encouraged. Function names should be as verbose as is practical to fully describe their purpose and behavior.
Function names should be verbs or verb phrases to show the action the function is providing or performing.
If you are going to use non-standard abbreviations in the your naming conventions, explain your abbreviations in the main program comment block.

For example:

function kilometers = convertMilesToKilometers(miles)

Functions returning a boolean type should generally start with verbs like, is, has, can or have, etc.

For example:

function output = isValidString(...);
function output = canUpdate(...);
function output = haveAllDate(...);

If a number of functions are declared in the same scope, a prefix can be added to clearly show their scopes.

atomsInstall(...);
atomsLoad(...);
atomsIsLoaded(...);

Arguments

Arguments are subject to the same guidelines as variable names. We don't want a bunch of functions like: doStuff(A, B, C). In most cases, we'd like to be able to tell how to use a function by just looking at its declaration.

Function arguments should be separated by spaces, both when the function is defined and when it is called.

However,

there should not be any spaces between the arguments and the opening/closing brackets
there should not be any spaces between the function name and the opening bracket

For example:

function getUserData( username, password, variable ); // incorrect spaces next to brackets
function getUserData(username,password,variable);     // incorrect no spaces between arguments
function getUserData(a, b, c);                        // incorrect, what do a, b, and c hold?
function getUserData (username, password, variable);  // incorrect, space just after the function name
function getUserData(username, password, variable);   // correct

Input and output arguments check

Number (mandatory)

if 1 > rhs || rhs > 2 then
    error(msprintf(gettext("%s: Wrong number of input arguments: %d to %d expected.\n"), "atomsInstall", 1, 2))
end

Type (mandatory)

if type(packages) <> 10 then
    error(msprintf(gettext("%s: Wrong type for input argument #%d: String array expected.\n"), "atomsInstall", 1));
end

Size/Dim (if needed)

if size(packages(1, :), "*") > 2 then
    error(msprintf(gettext("%s: Wrong size for input argument #%d: mx1 or mx2 string matrix expected.\n"), "atomsInstall", 1));
end

Value (if needed)

if and(section<>["user", "allusers"]) then
    error(msprintf(gettext("%s: Wrong value for input argument #%d: ''user'' or ''allusers'' expected.\n"), "atomsAutoloadAdd", 2));
end

Messages

All messages to the user must be normalized to follow convention. See Localization in English - Standard messages

Documentation

Every function must have a documentation block that contains at a minimum:

A description of the function
All of the arguments
All of the possible return values

Indent style

Use 4 spaces per indentation level.
Tabs or Spaces?
- Never mix tabs and spaces.
- Code indented with a mixture of tabs and spaces should be converted to using spaces exclusively.
- For new projects, spaces-only are strongly recommended over tabs. Most editors have features that make this easy to do.
Lines should have no trailing whitespace at the end.

Quotes

To avoid confusion with the transpose operator, single quotes (') to delimit character strings are prohibited .

Operators

All binary operators (operators that come between two values), such as +, -, =, ~=, ==, >, etc. should have a space before and after the operator, for readability. For example, an assignment should be formatted as foo = bar; rather than foo=bar;
Unary operators (operators that operate on only one value), such as ~, should not have a space between the operator and the variable or number they are operating on.

Line Length

For readability lines should try to be under 80 characters wide, in certain cases this is not possible or practical so it is allowable to have lines that are at an absolute maximum of 100 characters wide when it is absolutely necessary.(Functions which take lots of parameters are not exceptions.)

Loop Indices

Loops are the only occasion where a short variable name (such as a single character) are permitted, and encouraged when it's the index for a looping construct. Unless you already have a specific counting variable, use i as the variable for the outer loop. When there is a loop inside that loop, it's index should be j, followed by k, and so on.

for i=1:10
    for j=1:10
        for k=1:10
            foo(i, j, k);
        end
    end
end

Alignments

For declarations not separated by blank lines, follow these alignment rules:

Use vertical alignment to enhance the readability of declarations.
Provide, at most, one declaration per line.
Align the initialization delimiters.
When the declaration overflows a line, break the line and add an indentation level for those lines that wrap. The preferred places to break, in order, are: (1) the comment delimiter; (2) the initialization delimiter;

In a nutshell, statements should be aligned wherever this enhances readability.

rhs        = argn(2);
nbAdd      = 0;
autoloaded = [];

There are a number of places in the code where white space can be included to enhance readability even if this violates common guidelines. Many of these cases have to do with code alignment.

Number of Statements Per Line

Start each statement on a new line.
Write no more than one simple statement per line.
Break compound statements over multiple lines.

For example:

use

if isTrue() then
    disp("True");
else
    disp("False");
end

rather than

if isTrue() then disp("True"); else disp("False"); end

license block

The license block should be at the top of the file (1st line)
Each time a change occurs in the file, the year should be updated.

The standard license block is the following one:

// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
// Copyright (C) Scilab Enterprises - 20xx-2012 - Firstname LASTNAME <firstname.lastname@scilab.org>
// 
// This file must be used under the terms of the CeCILL.
// This source file is licensed as described in the file COPYING, which
// you should have received as part of this distribution.  The terms
// are also available at    
// http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt

For demos and tests, the following one should be used:

// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
// Copyright (C) Scilab Enterprises - 20xx-2010 - Firstname LASTNAME <firstname.lastname@scilab.org>
//
// This file is distributed under the same license as the Scilab package.