Configure Code Analyzer - MATLAB & Simulink (original) (raw)

The Code Analyzer checks code and provides information about errors and warnings. To configure the Code Analyzer, place a file namedcodeAnalyzerConfiguration.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 toerror. Syntax errors still prevent execution even if their severity is changed or the message disabled.

This file configures the Code Analyzer checks performed for theresources 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. ThecodeAnalyzerConfiguration.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.

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 namesize, error, orlength.

The "MyVariableCheck" check has these properties.

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.

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 andif, that can be nested.

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

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.

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.

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.

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 likeisEnabled is accepted.

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

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

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.

This table shows additional regular expression examples for naming conventions.

See Also

Apps

• Code Analyzer

Objects

• codeIssues

Functions

• matlab.codeanalysis.validateConfiguration | matlab.codeanalysis.refreshConfiguration

Topics

• Check Code for Errors and Warnings Using the Code Analyzer
• MATLAB Code Analyzer Report
• Index of Code Analyzer Checks