Metrics

Required role  Rule Management
Access  CodeChecker Server →  Rules Configuration →  Metrics

Metrics are numeric values deduced from the analysis of an application's source code. These values are used in quality rules to help determine code quality.

Metrics are based on metric models. A metric model is a script that defines the actions to carry out and their required properties. The metric created from a metric model must be instantiated to be used in a quality rule: this means values for each of the model's properties are defined to conform to the specific quality rule’s context.

The same metric can be used in multiple quality rules, depending on the validation expression defined in each quality rule.

Example

You want to create a quality rule to make sure the word 'TODO' is not found in the source code or the comments. The metric used in the quality rule needs to find the occurrences of this word.

To create the required metric, you will need to use the SEARCH_WORD metric model. When you instantiate the metric, you will define the following properties:

  • for Word, select TODO,
  • for Case sensitive, select false,
  • for Search type, select CONTAINS,
  • for Include comments, select true.

The metric will be incremented by one every time the word 'TODO' is found in a source code or the comments during the execution of the quality rule.

Reference

For more information about metric models, refer to Metric models.

For more information about quality rules, refer to Quality rules.

Metrics

The  Metrics view is accessed from the  Rules Configuration node in the Navigator.

Enter any combination of the above search criteria, then click the Search button to display the results. To display the complete list, click the Search button without entering any search criteria.

Follow the subsequent steps to create a new metric.

Step 1   To access the Create Metric wizard, either click the  Create icon in the toolbar of the  Metrics search view, or right-click anywhere in the search list of the view and select  Create Metric.

Step 2   Define the metric's Code, Name and Description. These values are required to create a new metric. The Code cannot be changed once the metric is created, but the Name and Description can be edited later.

Click Next > to continue.

Step 3   Select a metric model from the Available Metric Models list. This value is required and cannot be edited once the metric is created.

Click Next > to continue.

Step 4   Instantiate the metric. These values are required to create a new metric but can be edited later.

  • Check the Languages the metric applies to.
  • Enter a Value for each of the metric model properties.

Click Finish.

Result   The new metric is created and its editor opens automatically. It is displayed in the search list in the  Metrics view.

Warning!

When a metric is used by one or several active quality rules, it cannot be edited anymore. To edit the metric, delete the active quality rule(s) that use it.

To open a metric's editor, locate it in the  Metrics search view, then either:

  • double-click on the item in the view,
  • right-click on the item in the view and select  Edit, or
  • select the item in the view and click the  Edit icon in the toolbar.

The editable values are all located in the  Metric tab in the metric's editor. The  Quality Rules tab displays the list of quality rules that employ the metric. Double-click on a quality rule to access its editor.

Save the changes (, Ctrl+S or File > Save).

The Metric editor

Code
This field displays the metric's unique ID defined when creating the metric. Once a metric is created, it is not possible to edit this code.
Name
The metric's name should reflect the numeric value deduced from the analysis of the source code to be easily identified.
Description
Use this description to give as many details as possible about the numeric value that should be obtained when this metric is used.
Exploited Metric Model

This field displays the metric model selected when creating the metric. To access the metric model's editor, click the metric model's name.

Once a metric is created, it is not possible to edit the metric model selected. If the metric model needs to be changed, the metric should be deleted and a new one created with the correct metric model.

Check the language(s) to which the metric applies.

Pay attention to the languages selected and check all the potential languages the metric could apply to. If a certain language is not selected for a metric, the quality rules using this metric will not be executed on applications written in that language.

Example

You create a metric and only check the RPG language. You use this metric in a quality rule. This quality rule will not be executed during a code review process if the target application is not written in RPG.

You can track executed rules in the campaign logs. They include messages at verbose level for any skipped rules because they do not apply to your source.

Name, Type & Description
The Name, Type and Description columns give details on which value to give the properties of the selected metric model.
Value
If the metric model includes specific properties, select a Value from the drop-down list or enter it manually for each available property, depending on the numeric value that should be deduced from the source code's analysis.
Warning!

Deleted metrics cannot be accessed or recovered.

You cannot delete metrics that are currently being called by one or more quality rules. You must first delete all of the rules that employ it before deleting the metric.

To delete a metric, either right-click on it in the  Metrics search view and select  Delete, or select it and click the  Delete icon in the toolbar. Click OK to confirm or click Cancel to keep the metric.