Table of Contents

MonkeyProof MATLAB Coding Standard++

Table of Contents

Introduction

• Naming conventions
  • Name length
  • Loop iterator naming
  • Negated boolean names
  • Parent / child name redundancy
  • Variable casing
  • Function casing
  • Class casing
  • Property casing
  • Package casing
  • Event casing
  • Struct field casing
  • Constant casing
  • Enumeration member casing
  • Name shadowing
  • Names to avoid
  • Name-value pair casing
  • Test suffix
  • Name class object
• Layout & comments
  • Comment blocks
  • Function indentation
  • Whitespace in statements
  • Whitespace after characters
  • Line length
  • Indentation length
  • Comments on poorly written code
  • Equals sign alignment
  • Commas in rows
  • Line continuation with operators
  • Methods/Properties blocks with duplicate attributes
  • Whitespace at the end of a line
  • Use spaces instead of tab characters.
  • Properties blocks before methods blocks
• Statements & expressions
  • Constant definitions at top
  • Magic numbers
  • Function calls without inputs
  • One statement per line
  • If else
  • Switch otherwise
  • Mixed types in expressions
  • Parentheses in logical expressions
  • Parentheses in mathematical expressions
  • Assert inputs
  • Global variables
  • Constant conditional statements
  • Group struct field definitions
  • Return keyword
  • Dependencies known
  • Try for exception handling
  • Floating-point comparisons
  • Cell arrays
  • Zero before decimal point
  • Abstract class instantiation
  • Command syntax
• Higher level rules
  • Complexity
  • Number of function arguments
  • Constructors with single output
  • Scripts
  • Editor warnings
  • Getters and setters
  • Mex-files
  • Nesting depth
  • Reuse of iterator variables
  • Nested functions
  • Missing methods declarations and implementations
  • Mismatch input and output declarations and implementations
  • First output constructor
  • Iterator variables outside loop
  • More input arguments than expected
  • Superclass property implementation
  • Java dependency
  • Method access permissions
  • Write interpretable code
• Security
  • Eval-functions
  • Shell escape
  • Security weboptions
  • Security XML reading
  • Constant variable names
  • Security Username and Password

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 rules 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 rules described here can be checked using CC4M by MonkeyProof Solutions. The checkable rules are indicated by this logo at the top. These rules are configured in the predefined MonkeyProofSolutions configurations set available with the tool. For instructions on how to check your code against a coding standard, see the video below. The steps are also described below the video.

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

1. Install CC4M. If you have not purchased the tool yet, you can do so here. Alternatively, you could request a free trial license there.
2. Open CC4M 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.

Structure of this document

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

• Naming conventions: Rules in this chapter describe how variables, functions etc. can be named in a consistent and insightful manner.
• Layout & comments: This chapter contains rules to help improve readability of your code for yourself and for others. There are rules on whitespace, comments and more.
• Statements & expressions: The rules 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 rules: This chapter contains (among others) coding standards on higher-level objects such as functions or files.
• Security: This chapter contains rules on potential security risks.

Rule template

Every rule is structured as follows:

Rule name

Avoid:

One or more code examples to avoid using.

Instead use:

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

Severity levels

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

• Level 1 - Certainly a programming error
• Level 2 - Very likely a programming error
• Level 3 - Programming pitfall/undesired programming construct/accident waiting to happen
• Level 4 - Design issue with high impact on reliability or maintainability
• Level 5 - Design issue with low impact on reliability or maintainability
• Level 6 - Portability or performance issue or high impact other issue
• Level 7 - Comment related issue or medium impact other issue
• Level 8 - Naming convention or low impact other issue
• Level 9 - Style related issue
• Level 10 - Controversial issue or issue with a relatively high false positive rate

Each rule in this coding standard has a severity level attached to it. These severity levels are set in the CC4M and one can configure for which severity levels to check. The severity levels are related to the severity levels of Tiobe's TICS tooling.

Expansion of the MonkeyProof MATLAB Coding Standard

This standard includes the rules of the MonkeyProof MATLAB Coding Standard which can be found here and mainly adds naming conventions to it amongst some other rules. Each unique rule has its own unique rule identifier.

The following rules are different:

• NAMING-1 in this standard replaces NAMING-20 from the MonkeyProof MATLAB Coding Standard. This rule is about the length of variable names.

The following rules are an addition:

• NAMING-5 a rule on variable casing.
• NAMING-6 a rule on function casing.
• NAMING-7 a rule on class casing.
• NAMING-8 a rule on property casing.
• NAMING-9 a rule on package casing.
• NAMING-10 a rule on event casing.
• NAMING-11 a rule on struct field casing.
• NAMING-12 a rule on enumeration member casing.
• NAMING-13 a rule on enumeration member casing.
• STAT-15 a rule on minimizing the use of return.
• STAT-20 a rule on avoiding the use of cell arrays.
• LAYOUT-10 a rule on binary operators in multi-line statements.
• FCNS-27 a rule on writing interpretable code.

Naming conventions

The rules 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 rules (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

Variable casing

Avoid:

foo_bar = 1;
EggsBenedict = 0;
theHTMLPage = "www.test.com";

Instead use:

fooBar = 1;
eggsBenedict = 0;
theHtmlPage = "www.test.com";

Function casing

Avoid:

compute_values()
GetBestCandidates()

Instead use:

computeValues()
getBestCandidates()

Class casing

Avoid:

theClassName
other_class_name

Instead use:

TheClassName
OtherClassName

Property casing

Avoid:

Chair.ArmRest
Chair.sell_price

Instead use:

Chair.armRest
Chair.sellPrice

Package casing

Avoid:

+thePackageName
+another_package

Instead use:

+thepackagename
+anotherpackage

Event casing

Avoid:

classdef AmplitudeControl < handle
    events
        buttonPushed
        BUTTON_RELEASED
    end
end

Instead use:

classdef AmplitudeControl < handle
    events
        ButtonPushed
        ButtonReleased
    end
end

Struct field casing

Avoid:

circleData.Coordinates
circleData.radius_std

Instead use:

circleData.coordinates
circleData.radiusStd

Constant casing

Avoid:

r = 2.86e-23;
base_response = "Hello mr/ms ";

Instead use:

R = 2.86e-23;
BASE_RESPONSE = "Hello mr/ms ";

Enumeration member casing

Avoid:

classdef TheClass < handle
    enumeration
        chargingFrom0
        FULL
    end
end

Instead use:

classdef TheClass < handle
    enumeration
        ChargingFromEmpty
        Full
    end
end

Name shadowing

Names to avoid

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

The 'test' suffix

Name class object

Avoid:

classdef CarAnalyzer
	methods
		function velocity = initialVelocity(theCar)
			velocity = theCar.velocity;
		end
		
		
		function position = initialPosition(theVehicle)
			position = theVehicle.position;
		end
	end
end

Instead use:

classdef CarAnalyzer
	methods
		function velocity = initialVelocity(theCar)
			velocity = theCar.velocity;
		end
		
		
		function position = initialPosition(theCar)
			position = theCar.position;
		end
	end
end

Layout & comments

This chapter contains rules to help improve readability of your code for yourself and for others. The rules on indentation and whitespace make the code more visually appealing whereas rules 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

Tab characters

Properties blocks before methods blocks

Statements & expressions

The rules 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 rules 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:

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

Instead use:

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);

Return keyword

Avoid:

if isempty(x)
    return
end

<rest of the code>

Instead use:

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

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;

Cell arrays

Avoid:

data    = {12, 3; 4, 5};
names   = {"Neo", "Trinity", "Smith"};

Instead use:

data    = [12, 3; 4, 5];
names   = ["Neo", "Trinity", "Smith"];

Zero before decimal point

Avoid:

THRESHOLD = .5;

Instead use:

THRESHOLD = 0.5;

Abstract class instantiation

Do not use the command syntax

Avoid:

verifyNameLength namePersonA namePersonB

Instead use:

verifyNameLength("namePersonA", "namePersonB")

Higher level rules

The rules in this chapter transcend individual statements. These higher-level rules 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

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

Nested functions

Missing methods declarations and implementations

Mismatch input and output declarations and implementations

Avoid:

methods(Static)
    out1 = getFolder(in2, in1)	
end

function [reportsFolder, isOk] = getFolder(in1, in2)
....
end

Instead use:

methods(Static)
    [reportsFolder, isOk] = getFolder(in1, in2)	
end

function [reportsFolder, isOk] = getFolder(in1, in2)
....
end

The first output of a constructor should be the object of the class

Avoid:

classdef ConstructorDesign

   properties
      computedValue
   end

	methods
		function x = ConstructorDesign()
			obj.computedValue = 100;
			x                 = 101
		end
		
	end
end

Instead use:

classdef ConstructorDesign

   properties
      computedValue
   end

	methods
		function obj = ConstructorDesign()
			obj.computedValue = 100;
			x                 = 101
		end
		
	end
end

Use of iterator variables outside the for loop

Avoid:

for iNode = 1 : numel(nodes)
    if valueIn(iNode) > threshold
		break;
	end
end

valueOut = iNode + 10;

Instead use:

idx      = 0;

for iNode = 1 : numel(nodes)
    ...
	
	if valueIn(iNode) > threshold
		idx      = iNode;
		break
	end
end

valueOut = idx + 10;

More input arguments than expected

Avoid:

function processTemperatures(Tin1, Tin2, Tin3)
	x = calculateMaxTemperature(Tin1, Tin2, Tin3);
end

function out = calculateMaxTemperature(Tin1, Tin2)
	out = max(Tin1, Tin2);
end

Instead use:

function processTemperatures(Tin1, Tin2, Tin3)
	x = calculateMaxTemperature(Tin1, Tin2);
end

function out = calculateMaxTemperature(Tin1, Tin2)
	out = max(Tin1, Tin2);
end

Superclass property implementation

Avoid:

classdef Measurement
    properties
        measurementDate
    end
end

classdef Pressure < Measurement
    properties
        measurementDate = today()
    end
end

Instead use:

classdef Measurement
    properties
        measurementDate
    end
end

classdef Pressure < Measurement
    methods
        function obj = Pressure()
            obj.measurementDate = today();
        end
    end
end

Avoid Java dependency

Method access permissions

Avoid:

classdef Table
    methods (protected)
        computeMass(obj)
    end
end

classdef Desk < Table
    methods
        function computeMass(obj)
            ...
        end
    end
end

Instead use:

classdef Table
    methods (protected)
        computeMass(obj)
    end
end

classdef Desk < Table
    methods (protected)
        function computeMass(obj)
            ...
        end
    end
end

Write interpretable code

Security

This chapter contains rules to help avoiding potential security risks.

Eval-functions

Shell escape

Avoid:

!mycommand

Instead use:

system('mycommand')

Security Server Certificate Usage

Avoid:

% During construction
opts = weboptions("CertificateFilename", "");
opts = matlab.net.http.HTTPOptions("CertificateFilename", "");

% Post-construction
opts.CertificateFilename = "";

Instead use:

%% Do not specify "CertificateFilename" at all:

% During construction
opts = weboptions();
opts = matlab.net.http.HTTPOptions();

%% Specify default certificates:

% During construction
opts = weboptions("CertificateFilename", "default");
opts = matlab.net.http.HTTPOptions("CertificateFilename", "default");

% Post-construction
opts.CertificateFilename = "default";

%% Specify a certificate file explicitly:

% During construction
opts = weboptions("CertificateFilename", "MyFile.crt");
opts = matlab.net.http.HTTPOptions("CertificateFilename", "MyFile.crt");

% Post-construction
opts.CertificateFilename = "MyFile.crt";

Security XML reading

Avoid:

content = xmlread(myFile);
p = matlab.io.xml.dom.Parser();
p.Configuration.AllowDoctype = true;
p.parseFile(myFile);

Instead use:

content = xmlread(myFile, "AllowDoctype", false);

% For matlab.io.xml.dom.Parser configurations, AllowDoctype is false by default.
p = matlab.io.xml.dom.Parser();
p.parseFile(myFile);

Constant variable names

Avoid:

username = 'myName';
password = 'myPassword';

Instead use:

username = fileread('C:\Users\my.name\name.txt');
password = fileread('C:\Users\my.name\pwd.txt');

Security Username and Password

Avoid:

import matlab.net.http.Credentials

creds = Credentials('Username', 'John', 'Password', 'secret');
weboptions("Username", "John", "Password", "secret");

Instead use:

import matlab.net.http.Credentials

% Ask the user to provide a username and password, for example using a dialog or prompt:
[username, password] = showLoginDialog();

creds = Credentials('Username', username, 'Password', password);
weboptions("Username", username, "Password", password);

Note: This is just one example of how to obtain credentials without hardcoding them. Ask your IT department for the available options.