Code Conventions for the Scilab Programming Language
- Code Conventions for the Scilab Programming Language
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.
function kilometers = convertMilesToKilometers(miles)
- Functions returning a boolean type should generally start with verbs like, is, has, can or have, etc.
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 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.
- 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
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
if 1 > rhs || rhs > 2 then error(msprintf(gettext("%s: Wrong number of input arguments: %d to %d expected.\n"), "atomsInstall", 1, 2)) end
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
All messages to the user must be normalized to follow convention. See Localization in English - Standard messages
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
- 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.
To avoid confusion with the transpose operator, single quotes (') to delimit character strings are prohibited .
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.
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.)
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
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.
if isTrue() then disp("True"); else disp("False"); end
if isTrue() then disp("True"); else disp("False"); end
- 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@example.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 <email@example.com> // // This file is distributed under the same license as the Scilab package.