For a quick introduction on how to check your code using CC4M, see this video.
The tool runs by clicking the shortcut (see section
Shortcut for the MATLAB Editor) or is started from the
More information on the user interface is given in section
The CC4M user interface. The
checker allows for checking one or more selected files, m-files in a
folder or even the m-files in a folder and its sub-folders. A choice can
be made between checking all m-files or only those with local changes
with respect to a SubVersion or GIT repository. Live Editor files can also be
checked, albeit with some limitations as described in section
Live Editor files. For obvious reasons, p-code files
(obfuscated versions of m-code files) cannot be analyzed by CC4M.
Results from the metrics and all checks are shown in one result report. This result report contains the following sections:
- Meta data
- Additional information
- List of checks and parameters with missing/duplicate configurations.
- List of disabled checks.
- List of toolboxes installed.
The content of most of these sections is described in section
Metrics. Upon running CC4M, the report is
saved as a webpage (
.html) in the reports folder automatically for
future reference. The report will be given a unique name based on a
When running CC4M for the first time (see section Complete and verify installation), the reports folder is created at a default location. For Windows this is:
For Mac this is:
For Linux this is:
The reports folder can be changed or requested from the command line or the GUI. See Function Reference for an overview of the options.
The checks are directly accessible from the Model Advisor. There are two ways to use the checks within the Model Advisor; either configure the checks within the Model Advisor, or select a configuration from the GUI. To configure and run the checks from the Model Advisor, use the CC4M node in the "By Product" section of the tree (see figures Options to use-(a) and Example to configure). Furthermore, the predefined configurations shipped CC4M and your own configurations are available from the "CC4M Tasks" section, see figure Options to use-(b) .
The graphical user interface of CC4M on startup is shown in the figure below. It can
be opened by entering
monkeyproof.cc4m.start() in your command window
or using the shortcut. The GUI consists of a number of tabs, each with
multiple controls. This section describes all of them.
The General tab lets you select what files to check. The first step is to select whether you would like to check a file, folder, or MATLAB project. After making a selection, the relevant controls are shown. The controls for each of the options are shown in the figure below.
After clicking File, several controls are shown.
By selecting Active in editor on the top switch, CC4M automatically selects the currently active file in the MATLAB editor. When the switch is set to Browse, the selected file(s) shown in the text field will be checked by CC4M.
The button is used to browse for the file(s) to run CC4M on. You can browse for any file with extension
.mlx. It is allowed to select multiple files. The results of all checked files are placed in one report. The files can also be selected by entering them in the text field. Multiple files can be selected this way by separating them with semicolons. Non-existing files will result in a warning and the button will be disabled until the selection is valid.
The switch labeled Changed files only (when enabled: ) allows you to narrow the selection of files by only running CC4M on the selected files that have changed locally with respect to your Git or SVN repository. For this option, all selected files must be within the same repository. When disabled (), selected files are checked regardless of their status with respect to the repository.
The bottom switch, Ignore exemptions allows you to switch off all exemptions to coding standards in your code for the duration of the run. For more information on exemptions, see section Exemptions. The behaviour of this switch is equal for all three options (File, Folder, Project).
If you would like to check the code of files in a folder, select the Folder at the top.
By selecting Current directory on the top switch, CC4M automatically selects the current directory for checking. When the switch is set to Browse, the selected folder shown in the text field will be checked by CC4M.
The button can be used to browse for the folder to run CC4M on. Similar to the File option described above, the folder can also be selected by entering it in the text field.
Include subfolders, when turned on, selects the m-files in the selected folder and in all subfolders. This option can be very useful for checking an entire codebase, or a section thereof.
Narrow the selection of files to check by enabling the Changed files only switch if desired. The selected folder must be (in) a repository for this to work. If the folder contains the repository in a subdirectory, no changed files are found.
MATLAB projects provide a convenient way to set the bounds of your code and to define startup and shutdown tasks (among others). By selecting the Project option in CC4M, you can easily check the files of a project.
Select Current project to have CC4M check the project that is currently open (if any). If there is no project open, the run cannot be started. This is also shown in the figure. By selecting Browse, the project file shown in the textfield will be checked.
Use the button to browse for a project to check (
.prjfile). Alternatively, enter the absolute path of the project file in the textfield.
Project files to be checked can be filtered by enabling the Skip files labeled 'Test' option. This removes all files labeled Test from the list of files that will be checked. Test files do not always have to meet (the same) coding standards as other files do. Applying the label to your test files is also useful for easily generating a testsuite for the project.
The files to check can be further filtered by enabling Changed files only. This supports filtering files in the project based on their Git or SVN status. The selection includes files added to the project that have not yet been committed. In the case of a Git repository, uncommitted changes and staged changes are considered 'changes'. Newly added files need to be staged to be considered as 'changes'. If your changes have been committed locally, they will not be checked by CC4M if the Changed files only option is enabled.
After choosing the right options and starting the run, the selected project will be loaded if it is not loaded yet. You will be prompted to agree to this. Please note that because only one MATLAB project can be open at a time, loading a project closes any other open project.
MATLAB projects were introduced in MATLAB R2019a. If you are using a release older than that, the Project option will be disabled.
Once all settings are valid, the button will be enabled. This button is available on every tab in the GUI. After clicking it, the settings are applied and CC4M will run the checks on the files you selected using the rule configurations file of your choice. This action hides the GUI. Before running the checks on the files or folders you have selected, the code to check will be temporarily added to the MATLAB path so that the relevant information for properly performing the code analyses is available. During the analysis, property values may be initialized when gathering class information, if the checked code has class definitions among them. This may cause unexpected behaviour if the calculation of the initial values of properties deals with peripherals such as printing to the command window or reading from or writing to files. Potential errors during the initialization of properties are caught and will not interfere with the code analysis.
After analyzing the report and applying changes accordingly, you might
want to run CC4M again to make sure the code satisfies the coding
standards. Opening the GUI again using the shortcut or
monkeyproof.cc4m.start()within the same MATLAB session restores the
selected GUI settings so that the same file(s) can easily be checked
again. Alternatively, use the rerun all button in the report that was
generated as described in section
The Configuration tab shown in figure Configuration tab of the CC4M GUI is used to select the rule configuration file that is used for checking your code. A rules configuration file is an xml file that can be used to map your own MATLAB coding standard onto the checks and reports of CC4M. When running CC4M for the first time after installation (see section Complete and verify installation), the default configuration is created in the default folder that contains the configurations. For Windows this is:
After installing the CodeChecker, the predefined configuration MonkeyProof MATLAB Coding Standard++ becomes active. For more information on configuring checks, see section Configuring checks.
When the top switch is set to Custom, it means that a custom configuration file is selected for use during the checks. When the switch is set to Predefined, a configuration shipped with CC4M will be used to run the checks. Choosing this option hides the configurations folder selection and Import rules configuration file(s) controls as they are irrelevant for predefined configurations. The window you see will look like the one shown in the figure below. For more information on predefined configurations, see section Predefined Configurations.
The button is used to select a folder in which your rules configuration files are stored locally. The folder can also be selected by typing it in the text field. Typing a non-existent folder will result in a warning and the button will be disabled until the selection is valid. If the selected folder exists, but contains no xml files, a warning and an additional button 'Place default configuration in selected folder' will be shown. Upon clicking this button, a configuration file with default settings will be placed in the selected configuration folder. Selecting a configuration folder is unavailable as long as the switch at the top of the tab is set to Predefined.
The Import rules configuration file(s) option can be used to import one or multiple configuration files from for example a network drive to the configurations folder you selected above. Clicking this button will open a dialog that lets you choose any number of xml files. Upon clicking Open, the selected files are copied to the rules configurations folder you selected. If any of the configuration files to import already exists in the destination folder, you will be asked whether or not to overwrite them. By importing a rules configurations file instead of directly linking to it, you still have access to it, even if there is no internet connection or if it changes. This button is unavailable as long as the switch at the top of the tab is set to Predefined.
The dropdown box under Rule configurations file lets you select a configuration file that is in the selected configurations folder. If the switch at the top of the tab The contents of this file are used to apply your coding rules to CC4M. Click the Open button next to the dropdown box to open the selected configurations file in the Configuration Editor. This lets you interactively edit the configuration file as described in section Configuration Editor. Click the New button next to the Open button to create a new configuration file. For MATLAB R2020b and newer, the description of the configuration set/file is shown below the dropdown box.
Under Run checks by priority, you can filter the checks you wish to run by the priority you appointed to each of them. At least one of the boxes must be checked. Information on this selection is also shown in the meta data of the report.
The Report tab, as shown in the figure below lets you change the folder in which the HTML reports generated by CC4M will be stored. If the entered folder does not exist, the folder and at most one parent will be created for you. In addition, there are some options that let you choose what to show in the report that is generated after the run:
By default, only check results show up in the HTML report. By enabling Include metrics, you can have CC4M include useful information such as a list of functions, a list of variables and a list of complexity values per function in the HTML report.
Use the Include passed checks option to have CC4M include entries for all checks in the HTML report, regardless of whether any violations were reported for them.
Use the dropdown menu to select the number of entries to show in the check result table.
On the Preferences tab, you can turn certain options on or off. The preferences available are listed below. These preferences can also be obtained and changed via the command line interface.
Switch on Hide the user interface when starting a run to have the CC4M user interface hide itself when the Run button is clicked. The user interface can be shown again using the shortcut (see section Shortcut for the MATLAB Editor) or the
monkeyproof.cc4m.startcommand. Set the preference via the command line :
Switch the Run unconfigured checks to the right to have CC4M run checks that are not in the selected configuration file. Default values are used for those checks. You can add unconfigured checks to your configuration file as described in section Update the configuration file. Set the preference via the command line :
Use the Open reports in a new tab preference to have CC4M open its reports in a new tab instead of in the currently active tab of the MATLAB web browser (if any). This allows you to compare the results of multiple reports. It must be noted that auto-fixes and the rerun functionality will only work for the most recently generated report. Set the preference via the command line :
With the Report violations when not entirely sure preference, you can choose whether you want CC4M to report violations when not completely sure about them. To illustrate this, consider the following example:
var = myUnknownFcn(); var.My_Field = true;
In this case, CC4M is unable to detect whether
varis a struct or an object. If it is a struct, it violates
checkStructFieldCasing. Only when this preference is switched on will this situation be reported as a violation. By keeping this preference switched off, you can reduce the number of reported violations that are not actually violations of your coding standards. Set the preference via the command line :
Switch the Smart indent files before checking to the right to have CC4M smart indent the selected files before checking them, or use the command line interface, see below. This feature for convenience purposes automatically modifies your code - it is your responsibility to make sure your code is (functionally) correct after these modifications.
With the Skip or check large files preference, you can choose what needs to be done with large files. Large file will take relatively long to process and may pollute the results report. Additionally, large files may be generated and not require checking at all. The preference has three options :
Ask every time: When one or more large files are selected for checking, you will be asked every run whether you would like to check or skip the large files.
Skip: Always skip large files if they are selected. Do not check them.
Check: Always check large files if they are selected.
Set the preference via the command line :
The File size threshold [kB] preference lets you specify the threshold in kilobytes above which selected files are considered 'large'. The value can be between 50 and 1000 kB. As a rule of thumb, you can assume that a thousand lines of code constitute about 50 kB. Set the preference via the command line :
The current value of a preference can be obtained , for example, by the
command below where
defaultValue is returned if the preference has not
been set yet.
- Smart indenting is always disabled for files in the MATLAB root since you are not allowed to change these.
The About tab as shown in the figure(#fig:AboutTab) below contains information about CC4M:
The installed version of the CC4M.
A button for opening the HTML documentation of CC4M.
A button for accessing the CC4M support forum.
A button for opening a license information dialog. From this dialog, you can extend or upgrade your CC4M license. This dialog is described in section License dialog.
Access the proxy settings by clicking Proxy settings.
CC4M has metrics and checks that are configurable. This way, the code checker can be adapted to fit the company's or the team's coding standards. A configuration file allows to define:
- Description of the check.
- Category of the check.
- Rule identifier the check is related to.
- Hyperlink to content of the rules.
- If the check is used (enabled) or not.
- Priority of the check.
- Severity level of the check.
- Parameter values: further customization.
The reports contain the configurations defined for the check and link it
to an internal rules, see the figure below. It also includes a link to
directly open the configuration of a specific check in the Configuration
Editor. If you have specified a rules link, this will be accessible by
clicking the rules ID in the report. If the link refers to a webpage,
the rules link must start with
If your rules link contains a local drive address (i.e.
C:\), links to
specific pages in a PDF will simply open the file to the first page.
In order to provide insight in the settings of a check, information on its parameters is given in the report generated by CC4M. For every check that is enabled and has at least one parameter, the name, description, type, value and allowed values are shown. This information is obtained from the active configuration file. A link is also included that can be used to open the Configuration Editor to a specific parameter. An example of the information on a parameter for the check on variable casing as given in the report is shown in the figure below.
Section Configuration Editor describes the Configuration Editor for CC4M. It is used to open the configuration file of your choice interactively. The Configuration Editor can be opened by using the Open button on the Configuration tab in the CC4M GUI. The selected configuration file will be activated and opened. The Configuration Editor can also be opened from the Meta data section in a CC4M report using the Open button next to the configuration file path. To start editing the configuration of a specific check or parameter, use the links in the check result tables of a CC4M report. You will not be able to save any configuration files in the folder for predefined configurations shipped with CC4M (see section Predefined Configurations).
You could also edit the XML file directly in the text editor of your choice. However, this is not recommended because it is unintuitive and error-prone. The Configuration Editor makes sure that the edits you make and save, make the configuration file pass validation.
If a new version of CC4M is released, new checks and check parameters may be added. Your existing configuration file can be updated so that it will include these missing parts with default values. After updating, the newly added check configurations can be edited so that they apply the settings reflecting your coding standards and rules. Configuration files can be updated using one of two syntaxes:
monkeyproof.cc4m.updateConfigurationFile(); % Update the specified configuration file. monkeyproof.cc4m.updateConfigurationFile('<myFolder>\<configName>.xml');
As described in section
Configuration Editor, this option is also available in
the Configuration Editor by clicking Add missing elements. If you have
run CC4M and a report was generated, it will include a section on
missing check or parameter configuration. It also includes a link to
directly update the configuration file. After using any of these last
two options, a dialog is shown that tells you what checks and parameters
were added. If you call
the MATLAB command window, the list of added checks and parameters is
given as an output to the function call.
Comments in the configuration file get lost during this process. It is therefore advisable to -if applicable- adjust the description of a check or parameter instead of placing the additional information in comments the xml file.
Empty lines in the xml file are also lost during this process.
It is not allowed to update a predefined configuration.
To allow for a better mapping of your coding standards onto your CC4M configurations file, one check can be configured multiple times. The Code Checker distinguishes between different configurations based on the rule identifier. This is useful for example when there are multiple guidelines on what MATLAB-installed functions to avoid using, each with their own rationale, ID and list of function names. The Configuration Editor fully supports multiple configurations per check, see section Clone and remove check configurations. Results for a check that is configured more than once do have an individual checks result table in the report. Based on the rules identifier you can distinguish between the different results.
If the same check is configured multiple times, the additional configurations of the check are ignored when checking your code if one of the following is true:
Not all rules IDs of the check configurations are unique.
The check has no configurable parameters (the results would be the same for every configuration of the check).
You can exempt specific configurations of a check or all configurations of the same check. This is described in section Exemptions.
There's the option to include other configuration files from within the active configuration file. This option allows one to stack rules that are split over several configuration files, for example a configuration file related to naming conventions, another configuration file related to layout and another configuration file related to code generation. More information about referencing configurations can be found in section Reference configurations.
If the checks available within CC4M do not cover something you want to have checked, please contact us at firstname.lastname@example.org.
A check or report can be disabled using your configuration. If a check/report is disabled, it will not be performed and you will therefore not see any results for it in the final report. However, a table listing all disabled checks and reports can be found at the bottom of the report. It also includes a link to the configuration of the check/report so that you can easily enable the check and change its configurations. For quick access to this table, a link to it is included in the metadata at the top of the report as described in section Meta data and summary, which also shows the number of disabled checks and reports.
You might want to exempt certain parts of your code from specific
checks. By doing this, results for those checks on those parts of the
code will not be contained in the report shown after CC4M is finished
checking your files. Code can be made exempt from checks in a way that
is similar to MATLAB's
mlint that lets you disable warnings in the
editor by using syntax like
%#ok<NASGU>. Every check has its own
unique five-letter exemption tag, except for the checks that you are not
allowed to add exemptions for:
These tags can be used to exempt a line of code from a check by placing
%@ok<MYTAG> behind it (where
MYTAG is the tag of a check) somewhere
in a comment on the line of code. By adding a '
*' before the tag
%@ok<``*``MYTAG>), you can exempt the entire file from a check. An
example is shown below:
x = rand(); if x > 0.99 %@ok<IFELS> This is my explanation on why I don't want an 'else' here. disp('Hurray!') return end %@ok<*AVFUN>
Normally (if the check is enabled), we would see this part of the code
show up in the report because the
if does not
else section. However, by using the
exemption tag for
checkIfElse, it will not show up in the report. On
the last line, we can see a file-wide exemption for checkAvoidFunctions.
Doing this will make sure that
return (or any
function whose use you configure as discouraged) is not reported as a
function to avoid for this file. The placement of this file-wide
exemption within the file is irrelevant, as long as it is a comment.
As described in section
Multiple configurations per check, a check can be
configured more than once. In order to exempt your code of a specific
configuration of a check (related to a specific rule) append the
exemption tag with a dash followed by the rule ID. For example, to
exempt your code of a configuration of
checkAvoidFunctions with rule
A1_0, add the exemption
The exemptions can be ignored by switching on Ignore exemptions in the GUI.
Multiple exemptions can be defined on a single line like so:
y = x>0.99 %@ok<IFELS, *AVFUN, SURSP-MYID> My explanation.
In order to easily add exemptions to your code, you can use the Add
exemptions column in reports generated by CC4M. This is shown in figure
Add exemptions where the button in the third row has
been clicked. Upon clicking the Add exemption button, an exemption tag
is added to the file in which the violation was found and the file is
opened at the place where you can add a comment on why the code is
exempt from the check. The exemption tag will include the ruleID (if
any) so that the automatically added exemption only exempts your code
for one of configurations of a check. This is shown at the bottom of the
figure. By clicking the Add file-wide exemption button, you can add a
file-wide exemption (with
*-notation) as described above. This feature
takes pre-existing comments and exemptions into account when inserting
the new exemptions.
For the automatic exemptions to work, the lines and line numbers at which to add the exemptions should not have been edited between running the check and clicking the Add exemption button. Doing so might result in a warning. After a button has been clicked and an exemption was added, the button will be disabled. This feature helps to keep track of the exemption buttons that have been clicked previously, but they do not reflect the most up-to-date state of the code. This feature for convenience purposes automatically modifies your code - it is your responsibility to make sure your code is (functionally) correct after these modifications.
In order to easily add an exemption to your code without using a CC4M report, you can use function
>> theTag = monkeyproof.cc4m.getExemption('checkAvoidFunctions');
This will return the exemption tag for the given check name as it can be used in your code (for example
%@ok<FCNPF>). You can provide the full check name including packages, only the check name or even a partial check name as the input.
The exemption tags of each of the checks are also given in this document under each individual description of the checks in section Checks.
To get an overview of all exemption tags, use
tagsTable = monkeyproof.cc4m.getAllExemptions();
This will return a table containing the exemption tag for every check:
- Note that adding exemptions is always disabled for MATLAB-installed files since you are not allowed to change these.
In the report, in the Meta Data and in the Summary sections, a Rerun all button can be used to quickly rerun CC4M using the settings that were used to create the report you are currently viewing. This is very useful to check if the changes you made after viewing the report result in improved rule compliance. It can also be useful if the configuration file has changed.
The settings used for the rerun are stored in CC4M and not in the report. This has the following consequences:
Clicking the Rerun all button in an older report could result in using different settings for the rerun than were used for the initial run that resulted in the report. It is therefore recommended to use the rerun functionality from the most recently created report.
Clearing the CC4M code or calling
clear javacauses the stored inputs to be lost. Clicking the Rerun all button will then result in an error.
MATLAB sessions in which no CC4M report was created yet will trigger an error when a report is opened and the Rerun all button is clicked.
The rerun functionality does not directly use a list of files to check. Instead, it uses the settings used during the last run. This has to be kept in mind in the following situations:
If you checked a folder before, the folder will be checked again and any newly added files will be checked as well.
If you checked the MATLAB file that was opened in the editor, the rerun function will run the checks on the file that is open in the editor at the time of clicking the Rerun all button.
If you selected the option to check only the files changed with respect to a SubVersion repository, the list of files may change when you edit other files or commit your changes.
If no new CC4M run was started for over 72 hours within the same MATLAB session, you will be required to do so before being able to use the rerun functionality.
For several checks, auto-fixers are available. By clicking the Fix all button in the report (see figure Link to an auto-fixer in the CC4M report all violations for a specific (configuration of a) check are fixed. By clicking the Fix all in this file button all violations for a specific (configuration of a) check in a checked file are fixed. There is also a Fix on this line button, to fix individual violations. For this to work, the lines at which the violations were encountered should not have been edited between running the check and clicking the auto-fix link. Doing so might result in a warning. Similarly, fixing the same line twice will fix the violations the first time, and could trigger a warning on the second attempt. After a button has been clicked and its fix has been applied, the button will be disabled. This feature helps to keep track of the fix buttons that have been clicked previously, but they do not reflect the most up-to-date state of the code. After fixes have been applied, it is advised to run the check again to verify that the code now passes the check. Automated fixes are not available from the Model Advisor. This feature for convenience purposes automatically modifies your code - it is your responsibility to make sure your code is (functionally) correct after these modifications.
The checks for which fixes are currently available are:
- Note that automatic fixes are always disabled for MATLAB-installed files since you are not allowed to change these.
Starting from MATLAB R2016a, Live Editor files (with extension
*``.mlx) can be created. CC4M supports checking this file type as
well, both scripts and functions. However, there are some limitations
when checking these files that could lead to unexpected behavior:
Exemptions in Live Editor files that are not file-wide may not be taken into account and you might see results in the report for code you wished to exempt from specific checks.
Links to violations in Live Editor files refer to incorrect line numbers for MATLAB R2019b and older.
Because a conversion from binary to text must take place before checking the code, performance is poorer for Live Editor files.
In MATLAB versions before R2020a, when the active file in the editor is a Live Editor file, the text field in the GUI is empty and the run cannot be started until a file is selected through different means.
Auto-fixing Live Editor files is disabled.
Adding exemptions from the report is not possible.
Other than these limitations, Live Editor files are processed just like m-files.
checkUserDefinedFunctionCasing only checks the names of user-defined functions that are not methods. The names of methods are checked elsewhere. Furthermore, when this check is used in combination with checkFunctionPrefix, prefixes are subtracted before checking if the functions are cased according to the configured values.
the checkStructFieldCasing check suffers from the same limitation as checkStructFieldNaming: casing of dynamically assigned field names will not be checked.
checkMethodCasing does not report declarations of methods that are incorrectly cased if their functionality is specified in a separate function file. Additionally, getter and setter methods are ignored in this check, because their names are derived from property names that have a separate check. Constructor names are ignored during this check because they are named after the class. Finally, methods that overload a method of a superclass, are not checked here because those method names are not defined by the checked classdef file. Note, if a superclass has its own superclass(es), this is not taken into account.
This aligns equals signs in groups of expressions at multiples of the indentation length configured for checkIndentationLength. This way, the equals signs can be easily realigned after changes using the Tab key.