Introduction

The goal of this set of coding standards that can be automatically checked is to help you write consistent, clean, understandable and maintainable m-code. The resulting code will be more readable for both yourself and others. These guidelines are no strict rules that must be followed at all cost. They are simply there to help you write m-code well and you can deviate from them as you please.

Automatic compliance checking

Most of the coding standards described here can be checked using Code Checker for MATLAB by MonkeyProof Solutions. The checkable coding standards are indicated by this logo at the top. These coding standards are configured in the predefined MonkeyProofSolutions configurations set available with the tool. This set is the default selection after installing. For instructions on how to check your code against coding standards, see the video below. The steps are also described below the video.

You can check your code for compliance with the guidelines described here as follows:

1. Install Code Checker for MATLAB. If you have not purchased the tool yet, you can do so here. Alternatively, you could request a free trial license there.
2. Open Code Checker for MATLAB in one of two ways:
   • Click the shortcut created at the top of the screen next to the documentation search bar: .
   • Run monkeyproof.cc4m.start() from the command window.
3. Select whether you want to check one or more files, all files in a folder, or all files in a MATLAB Project.
4. Select what files/folder/project to check.
5. Further customization is available, for example checking a folder including or excluding all subfolders.
6. Click the Run button at the bottom to start checking your code.

The guidelines that require human judgment or are simply not possible to check statically in MATLAB are not part of this coding standard.

Structure of this document

The coding standards and guidelines are grouped under specific categories to help keep things organized:

• Naming conventions: Guidelines in this chapter describe how variables, functions etc. can be named in a consistent and insightful manner.
• Layout & comments: This chapter contains guidelines to help improve readability of your code for yourself and for others. There are guidelines on whitespace, comments and more.
• Statements & expressions: The guidelines and coding standards in this chapter are about how to use constructs such as if/else blocks, what built-in functions or keywords to avoid, how to best structure your statements etc.
• Higher level guidelines: This chapter contains (among others) coding standards on higher-level objects such as functions or files.

Guideline template

Every guideline is structured as follows:

Guideline name

Avoid:

One or more code examples to avoid using.

Instead use:

The example(s) above improved by complying with the guideline.

Severity levels

The following definition of the severity levels is used as a guide to make it easier to group the different guidelines and coding standards.

• Level 1 - Programming error (no discussion)
• Level 2 - Most likely a programming error (there are exceptions but in more than 50% of the cases this is a programming error)
• Level 3 - Accidents waiting to happen (there is no error at the moment but if somebody makes a change the house of cards might collapse)
• Level 4 - Important design issues
• Level 5 - Less important design issues
• Level 6 - Portability related rules, maintenance related issues
• Level 7 - Performance related rules
• Level 8 - Rules that deal with periphery such as comments, harmless preprocessor issues, etc.
• Level 9 - Naming conventions related rules
• Level 10 - Style related issue

As it currently stands, these severity levels have no further meaning in the Code Checker for MATLAB. They are however related to the severity levels of Tiobe's TICS tooling.

Naming conventions

The guidelines in this chapter describe how variables, functions etc. can be named in a consistent and insightful manner. If you wish to deviate from the casing guidelines (for example if you want your variable names snake_cased) at least make sure to apply consistent casing. Use the same casing scheme throughout your code so that classes, functions etc. can be easily identified by their name.

Name length

Avoid:

maximumValueOfTheEntireSetOfDataPoints = max(data);

Instead use:

maxData = max(data);

Loop iterator naming

Avoid:

for nodeIdx = 1 : 10
    for j = 1 : 3
        myGraph(nodeIdx).plotIt(j);
    end
end

Instead use:

for iNode = 1 : 10
    for jPoint = 1 : 3
        myGraph(iNode).plotIt(jPoint);
    end
end

Negated boolean names

Avoid:

if ~notValid && isNotFound
    error('My error message.')
end

Instead use:

if isValid && ~isFound
    error('My error message.')
end

Parent / child name redundancy

Avoid:

Beam.beamThickness
chair.weightOfChair

Instead use:

Beam.thickness
chair.weight

Name shadowing

Names to avoid

Function names document their use

Function name construction

Name-value pair casing

Avoid:

function plotMeasurement(options)

arguments
    options.number_of_lines             = 3
    options.precision                   = 2.5
    options.SHOW_LEGEND (1, 1) logical  = true
end

...

end

Instead use:

function plotMeasurement(options)

arguments
    options.NumberOfLines               = 3
    options.Precision                   = 2.5
    options.ShowLegend (1, 1) logical   = true
end

...

end

Descriptive names

Avoid:

function tk = convC2k(temp)

Instead use:

function temperatureK = convertCelsiusToKelvin(temperatureC)

The 'is' prefix

Abbreviations

Avoid:

arrTim

Instead use:

arrivalTime

Units in variable names

Avoid:

accelerationInMillimetersPerSecondSquared = 1000;

Instead use:

acceleration = 1000; % [mm/s^2]

The 'n' prefix

Avoid:

numberOfFiles
nrCars
lineCount

Instead use:

nFiles
nCars
nLines

The 'test' suffix

Layout & comments

This chapter contains guidelines to help improve readability of your code for yourself and for others. The guidelines on indentation and whitespace make the code more visually appealing whereas guidelines on comments increase the usability of the code they reference. By using ample whitespace, your code will look clean and the more complicated statements maintain their readability.

Comment blocks

Avoid:

%{ This is a comment.
This is also a comment.
%}

Instead use:

% This is a comment.
% This is also a comment.

Function indentation

Avoid:

function computeWeight(in)
    weight = 2 * in;
end

Instead use:

function computeWeight(in)
weight = 2 * in;
end

Whitespace in statements

Avoid:

isValid=y>0&&x==-1;

Instead use:

isValid = y > 0 && x == -1;

Whitespace after characters

Avoid:

while(ismember(x, [3,5,7,11,13]))
    x = x + 2;
end

Instead use:

while ismember(x, [3, 5, 7, 11, 13])
    x = x + 2;
end

Line length

Avoid:

theText = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut luctus arcu ex, at viverra nibh malesuada ac. Proin vel arcu leo.';

Instead use:

theText = ['Lorem ipsum dolor sit amet, consectetur adipiscing elit. ', ...
            'Ut luctus arcu ex, at viverra nibh malesuada ac. Proin vel arcu leo.'];

Indentation length

Avoid:

if x > 0
  if x < 2
    disp(x)
  end
end

Instead use:

if x > 0
    if x < 2
        disp(x)
    end
end

Comments on poorly written code

Avoid:

x = 2;
y = 3 * x; % TODO: take z into account.

% FIXME: This piece of ugly code is copied from StackExchange.
z=[1,23,8.1]*(x^3.1415)*sqrt(y);

Instead use:

x = 2;
y = 3 * x + z; 

z = [1, 23, 8.1] * (x ^ 3.1415) * sqrt(y);

Equals sign alignment

Avoid:

carWeight = 1.7 * 600;
nWheels = 2 + 2;
maximumSpeed = 190;

Instead use:

carWeight       = 1.7 * 600;
nWheels         = 2 + 2;
maximumSpeed    = 190;

Commas in rows

Avoid:

fig.Position    = [0 1000 1.5 130];
saying          = ['An apple a ' period ' keeps the doctor away.'];

Instead use:

fig.Position    = [0, 1000, 1.5, 130];
saying          = ['An apple a ', period, ' keeps the doctor away.'];

Line continuation with operators

Avoid:

isDone = isImplemented && ...
    isTested && ...
    isDocumented;

Instead use:

isDone = isImplemented ...
    && isTested ...
    && isDocumented;

Methods/Properties blocks with duplicate attributes

Avoid:

classdef Rocket
    properties (Access = public, Hidden = false, Constant)
        Fuel = "Nuclear"
    end
    
    properties (Constant = true)
        Capacity = 2
    end
end

Instead use:

classdef Rocket
    properties (Constant)
        Fuel = "Nuclear"
        Capacity = 2
    end
end

Whitespace in statements

Help text

Avoid:

function [avg, maxSize] = measureSize(obj, dim)
avg = mean(obj.Size, dim);
maxSize = max(obj.Size, dim);
end

Instead use:

function [avg, maxSize] = measureSize(obj, dim)
%MEASURESIZE Computes the size of the Item object.
%
% Input:
%   obj         The Item object.
%   dim         Dimension to measure.
%
% Output:
%   avg         Average size of the item.
%   maxSize     Maximum size of the item.

avg     = mean(obj.Size, dim);
maxSize = max(obj.Size, dim);
end

Whitespace around blocks of code

Avoid:

deltaX          = mean(xIn);
xOut            = xIn - deltaX;
scalingFactor   = newZ / currentZ;
xOut            = xOut .* scalingFactor;
xOut            = xOut + deltaX;

Instead use:

% Shift to origin.
deltaX  = mean(xIn);
xOut    = xIn - deltaX;

% Calculate scaling.
scalingFactor   = newZ / currentZ;
xOut            = xOut .* scalingFactor;

% Shift back.
xOut = xOut + deltaX;

Correct spelling

Avoid:

% get sclaing factor
scaling_factor = new_z / current_z;
x_out = x_out * scaling_factor; % now recslaed

Instead use:

% Get the scaling factor.
scalingFactor = newZ / currentZ;
xOut = xOut * scalingFactor; % Now rescaled.

Align struct definition

Avoid:

s = struct("name", "Albert", "age", 2021 - 1979, "isValid", ismember("Albert", allNames));

Instead use:

s = struct(...
    "name",     "Albert", ...
    "age",      2021 - 1979, ...
    "isValid",  ismember("Albert", allNames))

Statements & expressions

The guidelines in this chapter are about how to use constructs such as if/else blocks, what built-in functions or keywords to avoid or how to best structure your statements. Following these guidelines will ensure the individual statements in your code are complete and easy to read.

Constant definitions at top

Avoid:

function testConstants(x)
y = 3 * x;
MAX_Z = 100;
z = min(y, MAX_Z);
end

Instead use:

function testConstants(x)
MAX_Z = 100;

y = 3 * x;
z = min(y, MAX_Z);
end

Magic numbers

Avoid:

for iPick = 1 : 52
    disp(randi(13));
end

Instead use:

DECK_SIZE   = 52;
N_VALUES    = 13;

for iPick = 1 : DECK_SIZE
    disp(randi(N_VALUES));
end

Function calls without inputs

Avoid:

x = rand * 2;

Instead use:

x = rand() * 2;

One statement per line

Avoid:

persistent x, y

for iNode = 1 : 3, x = x + iNode; disp(x); end

Instead use:

persistent x
persistent y 

for iNode = 1 : 3
    x = x + iNode;
    disp(x);
end

If else

Avoid:

if x > 0
    saveData()
end

Instead use:

if x > 0
    saveData()
else
    % Do not save data.
end

Switch otherwise

Avoid:

switch reply
    case "Yes"
        saveData()
    case "No"
        clearData()
end

Instead use:

switch reply
    case "Yes"
        saveData()
    case "No"
        clearData()
    otherwise
        % Should not get here.
        error("Unknown reply " + reply)
end

Mixed types in expressions

Avoid:

d = a * b && c;

Instead use:

d = (a * b > 0) && c;

Parentheses in logical expressions

Avoid:

d = a && b || c;

Instead use:

d = (a && b) || c;

Parentheses in mathematical expressions

Avoid:

d = a * b + c;
h = f / 2 * g;

Instead use:

d = (a * b) + c;
h = (f / 2) * g;

Assert inputs

Avoid:

assert(~isempty(list))

Instead use:

assert(~isempty(list), 'ClassName:MethodName:ListIsEmpty', 'The list shall not be empty.')

Global variables

Constant conditional statements

Avoid:

if x > 0 || true
    disp(x)
end   

Instead use:

disp(x)

Group struct field definitions

Avoid:

s = struct("f", 2, "g", 3);

computeCost(s);
s.h = 'new field';

Instead use:

s = struct("f", 2, "g", 3, "h", 'new field');

computeCost(s);

Eval-functions

Keywords break, continue and return

Avoid:

if isempty(x)
    return
end

<rest of the code>

Instead use:

if isempty(x)
    % No further actions.
else
    <rest of the code>
end

Shell escape

Avoid:

!mycommand

Instead use:

system('mycommand')

Dependencies are known

Try for exception handling

Avoid:

try
    nElems = container.nElements;
catch
    nElems = 0;
end

Instead use:

if isfield(container, 'nElements')
    nElems = container.nElements;
else
    nElems = 0;
end

Floating-point comparisons

Avoid:

out = myFcn(in) == sqrt(3);

Instead use:

out = abs(myFcn(in) - sqrt(3)) < 1e-12;

Workspace variable ans

Debugging functions

Logical indexing

Avoid:

index = intersect(find(v > MIN), find(v < MAX));

Instead use:

index = (v > MIN) & (v < MAX);

Loop vectorization

Avoid:

dataResult = false(size(dataset));

for iElem = 1 : numel(dataset)
    if dataset(iElem) < limit(iElem)
        dataResult(iElem) = true;
    else
        dataResult(iElem) = false;
    end
end

Instead use:

dataResult = dataset < limit;

Zero before decimal point

Avoid:

THRESHOLD = .5;

Instead use:

THRESHOLD = 0.5;

Accessing other workspaces

Use switch blocks

Avoid:

if name == "Bill"
    ...
elseif ismember(name, ["Judith", "Bob"])
    ...
elseif name == "Steve"
    ...
else
    ...
end

Instead use:

switch name
    case "Bill"
        ...
    case {"Judith", "Bob"}
        ...
    case "Steve"
        ...
    otherwise
        ...
end

Variable in one unit

Avoid:

halfLifeTime = 580; % [s]
halfLifeTime = halfLifeTime / 3600; % [h]

Instead use:

SECONDS_TO_HOURS    = 1 / 3600;
halfLifeTime        = 580; % [s]
halfLifeTime        = halfLifeTime * SECONDS_TO_HOURS; % [h]

Higher level guidelines

The guidelines in this chapter transcend individual statements. These higher-level guidelines treat things like code complexity and function types.

Complexity

Number of function arguments

Avoid:

out = computeWeight(blockHeight, blockWidth, blockDepth, density, nBlocks, idx);

Instead use:

out = computeWeight(blockData, nBlocks, idx);

Constructors with single output

Avoid:

classdef Computer
    methods
        function [obj, out2] = Computer(in)
            obj.value = in;
            out2 = 2 * in;
        end
    end
end

Instead use:

classdef Computer
    methods
        function obj = Computer(in)
            obj.value = in;
        end
    end
end

Scripts

Editor warnings

Avoid:

%#ok<*ABCDE> Suppress a Code Analyzer warning in the entire file.

Instead use:

%#ok<ABCDE> Suppress the Code Analyzer warning on this line alone.

Getters and setters

Mex-files

Nesting depth

Repeated code

Ownership structure

Avoid:

function [out] = calculateSpeed(car)

out = car;

% do not remove fields from existing struct
car = rmfield(car, 'speed');

Instead use:

function [out] = calculateSpeed(car)

out = car;

% clear the field
car.speed = [];

Single responsibility

Commented out code

Reuse of iterator variables

Avoid:

for iNode = 1 : numel(nodes)
    ...
end

for iNode = 1 : 2 : 11
    ...
end

Instead use:

for iNode = 1 : numel(nodes)
    ...
end

for iValue = 1 : 2 : 11
    ...
end

Rewriting existing functions

Columns with implicit meaning

Avoid:

distance = sqrt(coordinates(:, 1) .^ 2 + coordinates(:, 2) .^ 2);

Instead use:

distance = sqrt(x .^ 2 + y .^ 2);

Nested functions

Input parameter dependency

Avoid:

function [meanV, meanA] = getMeanVandA(velocities, distances, timePts)
meanV = sum(distances) ./ sum(timePts);
meanA = velocities(end) ./ sum(timePts);
end

function vectorOut = processVector(vectorIn, vectorLength)
for iIdx = 1 : vectorLength
    vectorOut(ii) = processScalar(vectorIn(ii));
end
end

Instead use:

function [meanV, meanA] = getMeanVandA(distances, timePts)
meanV      = sum(distances) ./ sum(timePts);
velocities = distances ./ timePts;
meanA      = velocities(end) ./ sum(timePts);
end

function vectorOut = processVector(vectorIn)
for iIdx = 1 : length(vectorIn)
    vectorOut(ii) = processScalar(vectorIn(ii));
end
end