Configure Code Analyzer

The Code Analyzer checks code and provides information about errors and warnings. To configure the Code Analyzer, place a file named codeAnalyzerConfiguration.json in a resources folder. In this configuration file, you can add custom checks and modify existing checks of the Code Analyzer. Configure the Code Analyzer to enable or disable messages, customize message text, or change the severity of the displayed message.

Note

Changing the severity of a Code Analyzer message does not affect execution. Code is still executed even if the severity of a check has been set to error. Syntax errors still prevent execution even if their severity is changed or the message disabled.

Configuration file in a resources folder

This file configures the Code Analyzer checks performed for the resources folder's parent folder and its subfolders. The configuration is cached at the start of a MATLAB^® session. The MATLAB Editor does not automatically get the latest configuration when you add a new configuration file to a resources folder or update an existing file during a MATLAB session. To refresh the cache, call matlab.codeanalysis.refreshConfiguration.

You can verify that the file is a valid JSON file using the matlab.codeanalysis.validateConfiguration function.

Sample Configuration File

This code shows the contents of a sample configuration file. The codeAnalyzerConfiguration.json file uses JSON format, and // designates the text that follows as a comment.

{
    // Configuration File Information

    "name": "Acme Corp Guideline",
    "description": "Internal Acme Coding Guideline",
    "author" : "Alex",
    "schemaVersion" : "1.1.0",
    "guidelineVersion" : "1.0.0",


    // Base Configuration Settings
    // For better consistency, use "factory" for the configuration at the root of your codebase,
    // and use "closestParentFolder" for configurations nested deeper in your codebase

    "baseConfiguration" : "closestParentFolder",


    // New and Modified Checks

    "checks":
    {
        // ======================================
        // Enable additional Code Analyzer checks
        // ======================================
        "MyFunctionCheck" :
        {
            // Disallow use of evalin function
            "rule":
            {
                "template": "functionCall",
                "functionNames" : "evalin"
            },
            "severity" : "error",
            "messageText" : "Do not use evalin.",
            "enabled" : true
        },
        "MyVariableCheck" :
        {
            "rule":
            {
                "template": "variableName",
                "variableNames" : ["size", "error", "length", "max", "isa", "nargin" , "numel" , "nargout" ,"isequal" , "zeros" , "true" ,"false" ,"fullfile" ,"find", "get"]
            },
            "severity" : "warning",
            "messageText" : "Avoid using function names for variables.",
            "enabled" : true
        },
        "LLMNC" :
        {
            // Disallow very long lines (too many characters)
            "severity" : "error",
            "limit" : 1000,
            "enabled": true
        },
        "FCNOL" :
        {
            // Disallow too many outputs
            "severity" : "error",
            "messageText": "Too many outputs.",
            "limit" : 15,
            "enabled": true
        },

        // =================================================
        // Increase severity of default Code Analyzer checks
        // =================================================
        "GVMIS" :
        {
            // Do not use global variables
            "severity" : "error"
        },
        "EVLCS" :
        {
            // "eval" family of functions is slow and unclear
            "severity" : "error"
        },
        "NOANS" :
        {
            // Do not use "ans" as a variable
            "severity" : "error"
        },
        "CHAIN" :
        {
            // Chained logical operations like "a > b > c" are usually a bug
            //     For scalars, it should be: "(a > b) && (b > c)"
            //     For arrays, it should be: "(a > b) & (b > c)"
            "severity" : "error"
        }
    },

    // Naming Conventions

    "naming": {
        // ============================================================
        // Enable naming conventions for different types of identifiers
        // ============================================================
        "property" : {
            "casing" : "UPPERCASE_WITH_UNDERSCORES",
            "maxLength" : 12
        },
        "function" : {
            "casing" : "lowerCamelCase",
            "requiredPrefix": ["init", "initialize", "is", "calc", "find"],
            "minLength" : 4
        },
        "class" : {
            "casing" : "UpperCamelCase",
            "requiredPrefix": ["I", "Abstract", "UI"]
        },
        "method" : {
            "casing" : ["lowercase","lowerCamelCase"],
            "regularExpression" : "^([a-z]+|[a-z]+([A-Z][a-z0-9]*)*)$"
        },
        "localFunction" : {
            "casing" : "lowerCamelCase",
            "minLength" : 4
        },
        "nestedFunction" : {
            "casing" : "lowerCamelCase",
            "requiredPrefix": ["nested" , "nest" ],
            "minLength" : 4
        },
        "event" : {
            "casing" : "UpperCamelCase",
            "requiredSuffix" : "Event"
        },
        "enumeration" : {
            "casing" : "UPPERCASE",
            "regularExpression" : "^([A-Z]+)$"
        },
        "variable" : {
            "casing" : ["lowercase","lowerCamelCase"],
            "maxLength" : 12
        }
    }
}

Configuration File Information

You can optionally include the following properties in the configuration file. These properties do not affect the configuration. Each property accepts a string containing the relevant information.

"name" — Name of the configuration file
"description" — Description of the configuration file
"author" — Author name
"schemaVersion" — Schema version in the format "1.2.3"
"guidelineVersion" — Guideline version in the format "1.2.3"

Base Configuration Settings

A configuration file can inherit the rules of a configuration file contained in the resources folder of a parent folder. The property "baseConfiguration" specifies the base configuration to use and accepts these values:

"closestParentFolder" (default) — Use the configuration file found in the closest parent folder. If "baseConfiguration" is not defined, then the "closestParentFolder" setting is used by default.
"factory" — Use the standard MATLAB Code Analyzer configuration.

For more consistent Code Analyzer behavior, set "baseConfiguration" to "factory" for a configuration file at the root of your code base, and set "baseConfiguration" to "closestParentFolder" for configuration files nested deeper in your code base.

Add New Checks or Modify Existing Checks

You can configure the Code Analyzer add new checks or modify existing checks. To configure checks, add a "checks" property containing a JSON array where each element corresponds to a specific check being added or modified. Each element must have a check ID and properties depending on what type of check it is.

Add Custom Checks for Existing Functions

You can configure the Code Analyzer to display a check when specific functions are used. To create a new check, you must assign a check ID that is a valid MATLAB identifier. For example, define "MyFunctionCheck" to check for an evalin function call.

The "MyFunctionCheck" check has these properties.

Property Name	Example	Description
`"rule"`	"rule": { "template": "functionCall", "functionNames" : "evalin" }	Define the rules for the custom check. The `"rule"` field contains a JSON array containing these fields: `"template"` — Define the template as `"functionCall"` so the message is generated when the specified functions are called. `"functionNames"` — Define the names of the functions that trigger the custom check. Specify a string or string array containing the function names.
`"messageText"` (optional)	"messageText" : "Do not use evalin."	Specify the text displayed in the Code Analyzer message.
`"severity"` (optional)	"severity" : "error"	Specify the check severity as `"warning"`, `"error"`, or `"info"`. Messages that have been changed to `"error"` do not prevent execution.
`"enabled"` (optional)	"enabled": true	Specify whether this check is enabled in the MATLAB Editor.

Add Custom Checks for Specified Variable Names

You can configure the Code Analyzer to display a check when specific variable names are used. To create a new check, you must assign a check ID that is a valid MATLAB identifier. For example, define "MyVariableCheck" to check for variables with the name size, error, or length.

The "MyVariableCheck" check has these properties.

Property Name	Example	Description
`"rule"`	"rule": { "template": "variableName", "variableNames" : ["size", "error", "length"] }	Define the rules for the custom check. The `"rule"` field contains a JSON array containing these fields: `"template"` — Define the template as `"variableName"` so the message is generated when the specified variable names are used. `"variableNames"` — Define the variable names that trigger the custom check. Specify a string or string array containing the variable names.
`"messageText"` (optional)	"messageText" : "Avoid using function names for variables."	Specify the text displayed in the Code Analyzer message.
`"severity"` (optional)	"severity" : "warning"	Specify the check severity as `"warning"`, `"error"`, or `"info"`. Messages that have been changed to `"error"` do not prevent execution.
`"enabled"` (optional)	"enabled": true	Specify whether this check is enabled in the MATLAB Editor.

Configure Maximum Input and Output Arguments

You can configure the Code Analyzer to limit the number of input and output arguments for a function. Use the check ID "FCNIL" to specify the maximum number of input arguments for a function. Use the check ID "FCNOL" to specify the maximum number of output arguments.

The "FCNIL" and "FCNOL" checks have these properties.

Property Name	Example	Description
`"limit"` (optional)	"limit" : 10	Specify the maximum number of arguments.
`"messageText"` (optional)	"messageText" : "Too many outputs."	Specify the text displayed in the Code Analyzer message.
`"severity"` (optional)	"severity" : "error"	Specify the check severity as `"warning"`, `"error"`, or `"info"`. Messages that have been changed to `"error"` do not prevent execution.
`"enabled"` (optional)	"enabled": true	Specify whether this check is enabled in the MATLAB Editor.

Configure Maximum Characters per Line, Lines in a Function, and Nested Control Statements

You can configure the maximum characters per line, lines of code in a function, and nested control statements. Use the check ID "LLMNC" to specify the maximum number of characters (including white-space characters) in a line. Use the check ID "FCNLL" to specify the maximum number of lines of code for a function. Use the check ID "MNCSN" to specify the maximum number of control statements, such as for and if, that can be nested.

The "LLMNC", "FCNLL", and "MNCSN" checks have these properties.

Property Name	Example	Description
`"limit"` (optional)	"limit" : 100	Specify the maximum number of characters in a line, lines of code in a function, or number of nested control statements.
`"messageText"` (optional)	"messageText" : "Too many outputs."	Specify the text displayed in the Code Analyzer message.
`"severity"` (optional)	"severity" : "error"	Specify the check severity as `"warning"`, `"error"`, or `"info"`. Messages that have been changed to `"error"` do not prevent execution.
`"enabled"` (optional)	"enabled": true	Specify whether this check is enabled in the MATLAB Editor.

Modify Existing Code Analyzer Checks

You can use the configuration file to modify existing Code Analyzer checks. Use the check ID you want to modify as the check name. Then, specify the properties you want to modify and their new values. For example, to disable a check in the Editor, specify "enabled" : false.

To identify the check ID for checks in a given file, use codeIssues. For a full list of configurable checks, see Index of Code Analyzer Checks.

The built-in Code Analyzer checks have these properties.

Property Name	Example	Description
`"messageText"` (optional)	"messageText" : "Avoid growing array in a loop"	Specify the text displayed in the Code Analyzer message.
`"severity"` (optional)	"severity" : "info"	Specify the check severity as `"warning"`, `"error"`, or `"info"`. Messages that have been changed to `"error"` do not prevent execution.
`"enabled"` (optional)	"enabled" : true	Specify whether this check is enabled in the MATLAB Editor.

Configure Naming Conventions

You can configure the Code Analyzer to set naming conventions for different types of MATLAB identifiers, such as variables or functions. The Code Analyzer displays a check when a name does not match the configured naming conventions. To configure naming conditions, add a "naming" property containing a JSON array where each element corresponds to a type of MATLAB identifier. Each element must have a MATLAB identifier type and properties corresponding to its conventions.

The types of MATLAB identifiers that you can configure are:

"variable"
"function"
"localFunction"
"nestedFunction"
"class"
"property"
"method"
"event"
"enumeration"

Each configured identifier can have one or more properties corresponding to the naming conventions being applied.

Name Length

You can configure a minimum or maximum name length for identifiers. The Code Analyzer displays a message if an identifier name has fewer characters than the minimum or more characters than the maximum.

Check	Example	Description
`"maxLength"`	"maxLength" : 12	Specify the maximum number of characters for an identifier name.
`"minLength"`	"minLength" : 4	Specify the minimum number of characters for an identifier name.

Prefixes, Suffixes, and Phrases

You can configure required or disallowed prefixes and suffixes for identifiers. The Code Analyzer displays a message if an identifier does not follow the naming convention. You can also configure disallowed phrases, and the Code Analyzer displays a message if it finds the phrases anywhere in an identifier name.

Check	Example	Description
`"requiredPrefix"`	"requiredPrefix" : ["prop","property"]	Specify the prefix or prefixes that identifier names must begin with, as a string scalar or array.
`"disallowedPrefix"`	"disallowedPrefix" : ["get","set"]	Specify the prefix or prefixes that identifier names must not begin with, as a string scalar or array.
`"requiredSuffix"`	"requiredSuffix" : "orgABC"	Specify the suffix or suffixes that identifier names must end with, as a string scalar or array.
`"disallowedSuffix"`	"disallowedSuffix" : ["event", "EVENT"]	Specify the suffix or suffixes that identifier names must not end with, as a string scalar or array.
`"disallowedPhrase"`	"disallowedPhrase" : ["enum", "ENUM", "class", "_day"]	Specify the phrase or phrases that identifier names must not contain, as a string scalar or array.

Casing Checks

You can configure casing so that identifiers conform to one or more casing standards. Specify a "casing" property containing a string scalar or array where each element is a casing standard. If you specify more than one casing standard, then identifiers must satisfy at least one of them.

"function" : 
{
    "casing" : ["UPPERCASE_WITH_UNDERSCORES", "UpperCamelCase"]
}

Prefixes that match the requiredPrefix property and suffixes that match the requiredSuffix property are not included in casing checks. For example, the following check specifies a required prefix as well as upper camel case. In this check, the prefix is ignored when checking if the name adheres to the upper camel case rule, so a name like isEnabled is accepted.

"variable":
{
  "casing": UpperCamelCase,
  "requiredPrefix": ["is", "should", "has", "can", "did", "will"]
}

This table shows the values you can specify when setting casing standards.

Casing	Example	Requirements
`"lowercase"`	"casing" : "lowercase"	Contain all lowercase characters. Contain only characters and digits.
`"UPPERCASE"`	"casing" : "UPPERCASE"	Contain all uppercase characters. Contain only characters and digits.
`"lowerCamelCase"`	"casing" : "lowerCamelCase"	First letter must be lowercase. Subsequent words start with uppercase letter. Two consecutive letters can be uppercase. Contain only characters and digits.
`"UpperCamelCase"`	"casing" : "UpperCamelCase"	First letter must be uppercase. Subsequent words start with uppercase letter. Two consecutive letters can be uppercase. Contain only characters and digits.
`"lowercase_with_underscores"`	"casing" : "lowercase_with_underscores"	All characters must be either lowercase letters, digits, or underscores. No consecutive underscores.
`"UPPERCASE_WITH_UNDERSCORES"`	"casing" : "UPPERCASE_WITH_UNDERSCORES"	All characters must be either uppercase letters, digits, or underscores. No consecutive underscores.

Regular Expression Checks

You can create a custom naming convention check by specifying a regular expression. The Code Analyzer displays a message if the identifier name does not fully match the specified regular expression. Required prefixes and suffixes are not excluded from this check. Each identifier type can have only one regular expression check.

For more information on constructing regular expressions, see Steps for Building Expressions.

This table shows regular expressions for the casing options listed in Casing Checks.

Example Expression	Description	Matching Examples	Non-Matching Examples
"^[a-z0-9]+$"	Lowercase	`example`, `examplename`, `example123`, `123example`	`EXAMPLE`, `exampleName`, `example_123`
"^[A-Z0-9]+$"	Uppercase	`EXAMPLE`, `EXAMPLENAME`, `EXAMPLE123`, `123EXAMPLE`	`Example`, `ExampleName`, `EXAMPLE_123`
"^[a-z0-9][a-zA-Z0-9]*$"	Lower camel case	`example`, `exampleName`, `example123`, `123ExampleName`, `123exampleName`, `exampleNAME`	`Example`, `EXAMPLE`, `ExampleName`, `exampleName_123`
"^[A-Z0-9][a-zA-Z0-9]*$"	Upper camel case	`Example`, `ExampleName`, `Example123`, `123ExampleName`, `123exampleName`, `ExampleNAme`	`example`, `eXAMPLE`, `exampleName`, `ExampleName_123`
"^(?!.*__)[a-z0-9_]+$"	Lowercase with underscores	`example`, `examplename`, `example_name`, `example_123`, `123_example`, `_example_name`, `example_name_`	`EXAMPLE`, `exampleName`, `example__123`
"^(?!.*__)[A-Z0-9_]+$"	Uppercase with underscores	`EXAMPLE`, `EXAMPLENAME`, `EXAMPLE_NAME`, `EXAMPLE_123`, `123_EXAMPLE`, `_EXAMPLE_NAME`, `EXAMPLE_NAME_`	`Example`, `EXAMPLEnAME`, `EXAMPLE__123`

This table shows additional regular expression examples for naming conventions.

Example Expression	Description	Matching Examples	Non-Matching Examples
"^[a-z][a-z0-9]*$"	Match strings starting with a lowercase letter, followed by lowercase letters or digits. First character cannot be a digit.	`example`, `examplename`, `example123`	`EXAMPLE`, `exampleName`, `example_123`, `123example`
"^[A-Z][A-Z0-9]*$"	Match strings starting with an uppercase letter, followed by uppercase letters or digits. First character cannot be a digit.	`EXAMPLE`, `EXAMPLENAME`, `EXAMPLE123`	`Example`, `ExampleName`, `EXAMPLE_123`, `123EXAMPLE`
"^[a-z][a-zA-Z0-9]*$"	Match strings starting with a lowercase letter, followed by any combination of uppercase and lowercase letters and digits. First character cannot be a digit.	`example`, `exampleName`, `example123`, `exampleNAME`	`Example`, `EXAMPLE`, `ExampleName`, `exampleName_123`, `123ExampleName`, `123exampleName`
"^[a-z](?:[a-z0-9]+[A-Z]?[a-z0-9])$"	Match strings starting with a lowercase letter. No two consecutive characters are uppercase.	`example`, `exampleName`, `example123`	`Example`, `EXAMPLE`, `ExampleName`, `exampleName_123`, `123ExampleName`, `123exampleName`
"^[A-Z](?:[a-z0-9]+[A-Z]?[a-z0-9])$"	Match strings starting with an uppercase letter. No two consecutive characters are uppercase.	`Example`, `ExampleName`, `Example123`	`example`, `eXAMPLE`, `exampleName`, `ExampleName_123`, `123ExampleName`, `123exampleName`, `ExampleNAme`
"^(?!_)(?!.*__)[a-z0-9_]+(?<!_)$"	Match strings composed of lowercase letters, digits, and underscores, ensuring that the string does not start or end with an underscore and contains no consecutive underscores.	`example`, `examplename`, `example_name`, `example_123`, `123_example`	`EXAMPLE`, `exampleName`, `example__123`, `_example_name`, `example_name_`
"^(?!_)(?!.*__)[A-Z0-9_]+(?<!_)$"	Match strings composed of uppercase letters, digits, and underscores, ensuring that the string does not start or end with an underscore and contains no consecutive underscores.	`EXAMPLE`, `EXAMPLENAME`, `EXAMPLE_NAME`, `EXAMPLE_123`, `123_EXAMPLE`	`Example`, `EXAMPLEnAME`, `EXAMPLE__123`, `_EXAMPLE_NAME`, `EXAMPLE_NAME_`