3.9 Exemptions
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 Code Checker for MATLAB 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. 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 (so %@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 have an 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 3.4.3↑, 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 guideline) append the exemption tag with a dash followed by the guideline ID. For example, to exempt your code of a configuration of checkAvoidFunctions with guideline ID A1_0, add the exemption %@ok<AVFUN-A1_0>.
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.
3.9.1 Add exemptions automatically
In order to easily add exemptions to your code, you can use the Add exemptions column in reports generated by Code Checker for MATLAB. This is shown in Figure 3.13↓ 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 guidelineID (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.
3.9.2 Supporting functionality
-
In order to easily add an exemption to your code without using a Code Checker for MATLAB report, you can use function getExemption:
>> 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 3.7↑.
-
To get an overview of all exemption tags, use getAllExemptions:
>> tagsTable = monkeyproof.cc4m.getAllExemptions();
Limitation
- Note that adding exemptions is always disabled for built-in MATLAB files since you are not allowed to change these.