Customize Code Analyzer Checks Using Configuration File

Since R2023a

The Code Analyzer checks code and reports errors, warnings, and informational messages. You can identify potential coding issues and enforce project-specific coding standards by configuring the Code Analyzer. For example, you can improve code readability by setting limits on line length or function size, and by enforcing naming conventions. To customize Code Analyzer checks, create a configuration file and apply it to your code.

Create Configuration File

To configure the Code Analyzer, create a file named codeAnalyzerConfiguration.json in a resources folder. Within this configuration file, you can modify existing Code Analyzer checks and add custom checks. Add the resources folder in the folder where you want to apply the configured checks. This file configures the Code Analyzer checks for the resources folder's parent folder and all subfolders of that parent folder.

Sample Configuration File

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

{
    // Basic File Information
    "name": "Acme Corp Guideline",
    "guidelineVersion": "1.0.0",

    // Base Configuration Settings
    "baseConfiguration": "factory",

    // Modified and New Checks
    "checks": {
        "GVMIS": {
            // Do not use global variables
            "severity": "error"
        },
        "MyFunctionCheck": {
            // Disallow use of evalin function
            "rule": {
                "template": "functionCall",
                "functionNames": "evalin"
            },
            "severity": "error",
            "messageText": "Do not use evalin.",
            "enabled": true
        }
    },

    // Naming Conventions
    "naming": {
        // Set naming conventions for functions and variables
        "function": {
            "maxLength": 32, 
            "casing": ["lowerCamelCase","lowercase"]
        },
        "variable": {
            "maxLength": 32, 
            "regularExpression": "(^[a-z][a-zA-Z0-9]*$)|(^[A-Z][a-z0-9]*$)" 
        }
    }
}

Basic File Information

You can optionally include basic file information at the start of the configuration file. Specify one or more of the following properties as a string containing the relevant file information. These properties do not affect the configuration.

Property Name	Description	Example
"name" (optional)	Name of the configuration file	"name": "Acme Corp Guideline"
"description" (optional)	Description of the configuration file	"description": "Internal Acme Coding Guidelines"
"author" (optional)	Author name	"author" : "Alex"
"schemaVersion" (optional)	Schema version in the format "1.2.3"	"schemaVersion" : "1.1.0"
"guidelineVersion" (optional)	Guideline version in the format "1.2.3"	"guidelineVersion" : "1.0.0"

Base Configuration Settings

You can set your configuration file to inherit rules from the standard MATLAB^® Code Analyzer configuration or from another base configuration file located in the resources folder of the closest parent folder. Use the property "baseConfiguration" to specify which file to inherit rules from.

Property Name	Description	Example
"baseConfiguration" (optional)	Base configuration file to inherit rules from, specified as one of these values: "closestParentFolder" (default) — Inherit rules from the configuration file found in the closest parent folder. If "baseConfiguration" is not defined, then the "closestParentFolder" setting is used by default. "factory" — Inherit rules from the standard MATLAB Code Analyzer configuration.	"baseConfiguration" : "factory"

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.

Configure Custom Checks

Within the codeAnalyzerConfiguration.json file, specify your custom checks by adding the "checks" and "naming" properties. You can:

• Modify existing Code Analyzer checks and create new checks in the "checks" property.

• Specify checks for naming conventions in the "naming" property.

For example, this code changes the severity of the existing global variable check "GVMIS" from a warning to an error:

    "checks": { 
        "GVMIS":
        {
            // Increase severity of the default global variable check 
            "severity": "error" 
        }
    }

Note

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

Using the "checks" property, you can also change message text, disable checks, or configure checks to detect code that exceeds specified limits for line length, function size, nesting depth, or number of function arguments. In addition, you can flag the use of specific functions or variables by creating custom checks. For more information, see Modify Existing Code Analyzer Checks or Create New Checks.

Using the "naming" property, you can enforce a consistent coding style by defining naming conventions for different types of MATLAB identifiers. For more information, see Check for Certain Naming Conventions in Your Code.

Refresh and Verify Configuration

When you add a new configuration file to a resources folder or update an existing configuration file during a MATLAB session, the MATLAB Editor does not automatically get the latest configuration because the configuration is cached only at the start of a MATLAB session.

To apply the new or updated configuration file to the current MATLAB session, call matlab.codeanalysis.refreshConfiguration to refresh the cache.

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