Base Code Analyzer Directives
Overview
The Code Analyzer supports configuring specific code analysis metrics using directive comments, providing greater flexibility over the code analysis process.
Supported Code Analysis Metrics
The following code analysis metrics can be configured by specifying their corresponding metric codes in the comments:
| Metric Code | Metric Name |
|---|---|
| c3-broken-doc-links | Broken Documentation Links |
| c3-deprecated-type-usage | Deprecated Type Usage |
| c3-excessive-method-params | Too Many Parameters |
| c3-expired-deprecations | Expired Deprecations |
| c3-incomplete-method-docs | Incomplete Method Documentation |
| c3-hardcoded-credentials | Hardcoded Credentials |
| c3-hidden-funcs | Hidden Functions |
| c3-missing-docs | Missing Documentation |
| c3-ticket-mention | Ticket Mention Count |
| c3-todos-in-type-docs | Ticket Mentions in Type Documentation |
| c3-unticketed-todos | Un-ticketed TODOs / FIXMEs |
| c3-eslint | ESLint |
| c3-python-lint | Python Lint |
| c3-psr-clear-collection | PSR Anti-pattern: Unsafe invocation of clearCollection call |
| c3-psr-kv-stored-calc-field | PSR Anti-pattern: Stored Calc Field on Key-Value Type |
| c3-psr-loop-single-db-write | PSR Anti-pattern: Single database write in a loop |
| c3-psr-sleep-call | PSR Anti-pattern: time.sleep() or Thread.sleep() call |
| c3-psr-unfiltered-remove-all | PSR Anti-pattern: Unfiltered removeAll call |
| c3-psr-unlimited-fetch | PSR Anti-pattern: Unlimited fetch call |
More information about code analysis metric codes can be found in the BaseCodeAnalysis.Metric.Code.
Using Directive Comments
Code analysis metrics can be configured using directive comments with the following format:
Disable code analysis metrics for a block:
Textc3-analysis-disable <comma-separated code analysis metric codes> -- <justification>Disable code analysis metrics for a line (only available for JavaScript and Python):
Textc3-analysis-disable-next-line <comma-separated code analysis metric codes> -- <justification>Enable code analysis metrics:
Textc3-analysis-enable <comma-separated code analysis metric codes>
The comment must be placed above the code where you want the specified metrics to be configured. Please note:
c3-analysis-disable-next-lineis only available for JavaScript and Python files.- The metrics are automatically enabled on the next line if you used
c3-analysis-disable-next-lineto configure metrics.
Configuring all metrics is also supported using the following format, but we strongly recommend specifying the comma-separated metric codes explicitly to maintain clarity.
Disable all code analysis metrics for a block:
Textc3-analysis-disable -- <justification>Disable all code analysis metrics for a line (only available for JavaScript and Python):
Textc3-analysis-disable-next-line -- <justification>Enable all code analysis metrics:
Textc3-analysis-enable
While ESLint and Pylint offer their own directive comments to configure rules, we recommend using the directive comments we provide for better management of code analysis metrics.
Configure Metrics in JavaScript and TypeScript
Directive comments can be specified with block comments or line comments. Below are example formats of directive comments:
To disable code analysis metrics for a block of code:
// c3-analysis-disable <comma separated code analysis metric codes> -- <Reason>To disable code analysis metrics for a line of code:
/* c3-analysis-disable-next-line <comma separated code analysis metric codes> -- <Reason> */To re-enable code analysis metrics:
/*
* c3-analysis-enable <comma separated code analysis metric codes>
*/Please note you can split long directive comments across multiple lines for readability using block comments.
Examples for JavaScript
Example 1: Configuring Metrics for a Block in JavaScript
/*
* c3-analysis-disable c3-deprecated-type-usage, c3-hardcoded-credentials
* -- Using deprecated type for backward compatibility, credential is a placeholder value
*/
function example() {
var password = '12345';
MyDeprecatedType.testFunc(password);
}
// c3-analysis-enable c3-deprecated-type-usage, c3-hardcoded-credentialsExample 2: Configuring a Metric for a Line in JavaScript
// c3-analysis-disable-next-line c3-hardcoded-credentials -- Credential is a placeholder value used for test
var password = '12345';Configure Metrics in Python
Directive comments can be specified with line comments. Below are example formats of directive comments:
To disable code analysis metrics for a block of code:
# c3-analysis-disable <comma separated code analysis metric codes> -- <Reason>To disable code analysis metrics for a line of code:
# c3-analysis-disable-next-line <comma separated code analysis metric codes> -- <Reason>To re-enable code analysis metrics:
# c3-analysis-enable <comma separated code analysis metric codes>Examples for Python
Example 1: Configuring Metrics for a Block in Python
# c3-analysis-disable c3-psr-unfiltered-remove-all -- Remove stale entities used for test
def clearAllData(cls)::
# Code to clear data
c3.MyEntityType.removeAll({}, true)
pass
# c3-analysis-disable c3-hardcoded-credentials -- Credential is a placeholder value used for test
def setCredentials(cls):
password = "12345"
pass
# c3-analysis-enableExample 2: Configuring a Metric for a Line in Python
# c3-analysis-disable-next-line c3-hardcoded-credentials -- Credentials are a placeholder value used in test file
password = "12345"Configure Metrics in C3 Type
Directive comments can be specified with hidden comments in Type, field, or function declarations by noting your comments with /* and //. Below are example formats of directive comments:
To disable code analysis metrics for a block of code:
// c3-analysis-disable <comma separated code analysis metric codes> -- <Reason>To re-enable code analysis metrics:
/*
* c3-analysis-enable <comma separated code analysis metric codes>
*/Please note you can split long directive comments across multiple lines for readability using block comments. If there are any annotations for a Type, field, or function, the directive comments should be placed above the annotations.
Examples for C3 Type
Example 1: Configuring Metrics for a Block in C3 Type File
/*
* c3-analysis-disable c3-missing-docs -- This is a Type solely for testing.
*/
type TestType {
// c3-analysis-enable
/**
* The field used in the test case.
*/
testField: string
}Example 2: Configuring Metrics for a Field with Annotation in C3 Type File
/*
* c3-analysis-disable c3-missing-docs -- This is a Type solely for testing.
*/
type TestConfig mixes Config, Singleton {
// c3-analysis-enable
/**
* The API token to use in the test.
*/
@config(secret=true)
testApiToken: string
}