Code Conventions for the Scilab Programming Language

Functions

names

Scilab has not a good record of consistent naming.

For example:

function kilometers = convertMilesToKilometers(miles)

For example:

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

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,

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:

Indent style

Quotes

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

Operators

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:

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

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 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.

public: Code Conventions for the Scilab Programming Language (last edited 2015-07-01 09:37:14 by clement.david@scilab-enterprises.com)