Software Metric Reports

Overview

The metrics user interface is organized around metrics reports in which it is possible to display property values in various ways. To achieve greater flexibility, the metrics report is logically distinct from metrics data, similar to the way data organized in a table can be portrayed graphically in the form of many different charts.

In this sense, the process of attaching graphics representations (metrics reports) to a group of metrics data is called applying a metrics report to a particular group of metrics data.

Separating the data from the visual representation offers three important possibilities:

1. In a metrics report (which, for example, portrays a group of Halstead Parameters), it is possible to display various objects of observation (different modules, functions, and so on).
2. Different metrics reports (with different groups of metrics, different types of charts, differently presented information, and so on) can be applied to the same objects of observation (for example, the main() function).
3. It is possible to, over a single project, create a group of metrics reports which provides a complete overview of the project, and then to apply these reports to other projects, either in order to compare projects, or due to interest in a precisely specified group of metrics for each project.

Metrics Report

The main goal of introducing software metrics in DAC was enabling you to ascertain software quality, according to project-defined criteria, with a single glance at a report.

Every metrics report is displayed in its own window, which is on a par with Graph, Editor, Browser, and all other windows in DAC.

Figure shows a typical metrics report. Settings pertaining to the metrics context (the way in which metrics are displayed, see section "Metrics Context") are displayed in the left pane of the report, while metrics data from several selected C modules is displayed in the right pane.

Metrics Simple Report

The form in which a metrics report is typically displayed.

The selected objects of observation are a group of several modules from the same project folder.

The values of the parameter Comment Lines are displayed on module level, that is, the relative number of clear comment lines in each of the displayed modules. The data appears in the form of a Bar chart, and the manner of presentation is "Simple" — the real values of parameters obtained by metrics calculation are displayed. The enumerated features together form the metrics context and determine which metrics will be displayed and in which manner.

Therefore, to obtain the desired metrics report, objects of observation must be determined and the metrics context of the report must be set.

Objects of Observation

Before metrics reports can appear, it is necessary to select the desired objects of observation. By means of this procedure, you determine the group of objects for which you would like to view property values.

One of the following items can be selected as an object of observation:

Function,
Group of functions,
Module,
Logical group of modules,
Group of modules of your choice.

If you do not select an object of observation, the metrics reports will be empty.

To select an object of observation, do one of the following:

Right-click an object in DAC, and then select the Metrics command in the shortcut menu.

or

Select or position the insertion point on the desired object or in the desired window and, on the main menu, start the Metrics / Apply command.

Following table gives a detailed description of the ways in which you can select an object of observation from various DAC windows. The table does not show this, but it is understood that a right-click opens the shortcut menu, on which you should click Metrics; if you prefer making a selection by placing the insertion point on the object of your choice to using the shortcut menu, use the Metrics > Apply command instead.

After you have selected an object of observation in one of the ways enumerated, all existing metrics reports will display the newly-selected object of observation, as will all reports created from this point on. If there is no existing report, a new report will be created.

A selected object of observation will be saved until a new selection is made. On closing the project, the object of observation is saved in the Session File; in the next session, you can continue working exactly where you left off.

Table 6: Manner of selection of particular objects from various DAC windows  

DAC window

Object

Manner of selection

Editor

function

right-click or position the insertion point on the name of the function

module

position the insertion point in the Editor

Browser

function

right-click or position the insertion point on the name of the function

Flowchart

module

click anywhere in Flowchart (don’t select anything)

Graph

function

right-click or click the function node

group of functions

right-click or select a group of functions

Project
Window

function

right-click or select the name of the function in Logical View

module

right-click or select a module

group of modules

right-click or select a folder

project

right-click or select a Project Root directory

Messages

function

select a message (error or warning)

module

select a message (error or warning)

Metrics report

function

select the name of the function or the attached parameter value

module

select the name of the module or the attached parameter value

Metrics Context

The metrics context is a mode of displaying metrics, both in terms of graphics and manner of presentation. The metrics context is fully determined by choice of:

The level of viewing metrics data,
The type of metrics report,
The type of metrics parameter,
The manner in which property values are visualized.

The metrics context is a frame, independent of the metrics data you want to display. Applying the metrics context to specific objects of observation creates a complete metrics report. In this way, the metrics data you want to examine is distinct from the manner of their representation and visual presentation. This gives you the possibility of always viewing various metrics data in the same way.

Levels of Observation

The level of observation determines the scope of the metrics which are to be displayed.

It is possible to choose between the following levels of observation:

Function level,
Module level,
Group of modules level.

Which group of metrics values is to be displayed in metrics reports depends not only on the object of observation, but also on the level of observation, as shown in following table. You should keep this in mind, otherwise unexpected parameters will appear in a metrics report, with what will at first appear to be no discernible reason.

Table 7: The contents of metrics reports, depending on selected levels of observation and objects of observation  

Level of observation

Group of modules

Module

Function

Object of observation

function

function module

function module

function

group of functions

function modules from the group

function modules from the group

group of functions

module

module

module

all module functions

group of modules or project

group of modules

group of modules

all functions of a group of modules

For example, if the object of observation you have selected is a group of functions, and the level of observation you have selected is module level, the metrics of modules containing functions from the selected group will be displayed in the metrics report.

Types of Metrics Reports

The choice of one of the metrics report types determines the manner in which the metrics data collected will be presented.

Metrics data can be interpreted from various standpoints. For example, the data item stating "there are 200 comment lines in the program" contains a lot less information than does the data item stating "comment lines make up 12% of the program", or a data item concerning the distribution of comment lines between modules in the program. As a result, the following types of metrics reports have been developed:

Report on ordinary parameter values - Simple or multiple report.
Report on normalized parameter values - Cross parameter report.
Report on distribution of parameter values - Distribution report.
Report on average parameter values - Average report.

All enumerated types of metrics reports are described in detail in section "Types of Metrics Reports".

Types of metrics

In order to obtain the information which interests you in a metrics report, it is necessary to select the corresponding metrics. Each metrics parameter represents an item of information on one of the quantitative attributes of the source code.

Each metrics parameter has a name unique within its group (level of observation). Each metrics parameter is expressed in corresponding units. Parameters such as Lines or Statements appear as absolute numbers of lines of code or commands in the code, while parameters such as Comment Lines or Executable Statements appear in percentual form, relative to the total number of lines of code or commands in the code.

A complete list of metrics has been provided in section  "metrics in DAC".

Ways of Visualizing property values

property values and their interrelations can be observed by means of several types of graphics views. Each of these views allows the possibility of differently experiencing and interpreting parameter values.

The following types of charts are available for the visualization of property values:

Bar chart,
Column chart,
Pie chart,
Radar chart,
Table.

Each of these charts has its own advantages. A table is very practical for detailed comparison and an accurate overview of parameter values. Bar and Column charts are the standard for graphics display of larger sequences of data. A Pie chart is highly suitable for an overview of parameter distribution, and a Radar chart for simultaneous observation of larger numbers of values grouped in larger numbers of series.

Metrics Report Construction Mode

The metrics report Construction Mode is used during report preparation to choose the desired type of parameter and to choose the parameters themselves, as well as to choose the type of report (choice of chart). In Construction Mode, the left pane of the metrics report is a construction dialog box containing options for setting the metrics context of the report. The metrics report is initially displayed in Construction Mode to allow the metrics context to be set.

A metrics report in Construction Mode is displayed in following figure.

Three groups of options are discernible:

Parameters. Enables you to select the level of observation - the scope of metrics (group, module, function), and then to select the parameters themselves from the list
Report. Enables you to select the type of metrics report.
Chart. Enables you to select the chart in the form of which the metrics data will appear (manner of visualization).

Metrics Report in Construction Mode

A metrics report in Construction Mode

Once the metrics context has been set, it is possible to turn off the Construction Mode; the construction dialog will disappear from the report and the metrics report will take up the entire window area.

metrics on the list have been sorted according to alphabetical order. For Cross parameter and Average report types, it is possible to select more than one parameter from the list, whereas for Simple and Distribution report types, only one parameter from the list can be selected. If no parameter has been selected, an empty metrics report will appear.

Only Simple and Cross parameter types of report are possible for the "Group" level of observation. Selecting the "Group" type of metrics parameter will cause the type of metrics report to be changed to Simple, if another type of metrics report was previously chosen.

Changing the type of report does not change the list of selected parameters, unless the change demands a transition from a single parameter type of report to a type of report with more than one parameter and vice versa (for example, from the Simple to the Average type). In this case, the previous parameter configuration is saved and restored should you revert to the original choice.

Changing the type of chart has no influence on the other elements of the construction dialog box.

Metrics Template

The metrics template defines a possible view of the software metrics of a project. It is made up of one or more metrics contexts together with the metrics configuration.

The metrics template, just like the metrics context, is distinct from metrics data. A single metrics template a view of metrics can be applied to various projects, functions, modules, which enables you to view various logical wholes using a once-established criterion.

It is easiest to describe a metrics template as a set of metrics configuration and reports, but without specific metrics data.

Using metrics templates, it is possible to predefine many different views of the software metrics of a project. The metrics template of the Project Explorer (based on the criteria for project headway, estimates of time needed, and so on) will differ from the metrics template of the quality control department (which measures comment quality and extent, code complexity, and so on). In this way, the source code can at any time be checked from the aspect of quality control, meaning that as early as in the development stage, quality can be built it and the number of iterations "comments and corrections" reduced.

The following operations have been defined over the metrics template:

Creating a new metrics template;
Saving a metrics template to a file;
Reading a saved metrics template from a file.

When you save a metrics template, all existing metrics reports are saved in a file with an .MET extension. The metrics data alone does not belong to the metrics template and is saved by a different procedure, in a different location, the Metrics database. It is possible to open a metrics template saved in this manner from a different project and to apply metrics reports to the data of that project.

If the metrics template has been changed by adding a new metrics report or by altering one of the existing reports, you will be asked to save the changes on closing. Each newly-opened window with a metrics report is assigned to the currently active metrics template.

When a new project is created, an empty metrics template, which does not contain metrics reports, is automatically created with it. Once changes have been made in the metrics, the metrics template can be saved, at which time it can be named and its name is associated with the active project. The name of the active template is saved on closing the project, so that the project is opened each time together with the metrics template active during the previous session.

The name of the active metrics template is displayed on the DAC status bar, as shown in following figure (the name of the template is "Complexity"). The asterisk before the name of the template signifies that the metrics template has been changed since it was last saved.

All visual adjustments of individual metrics reports are saved in the metrics template file. Default values of visual attributes of metrics reports set using the Options > Software Metrics Charts command, as well as border values of metrics set using the Options > Software Metrics Calculator command are also saved.

Types of Metrics Reports by Value

The following sections describe individual types of metrics reports. The choice of metrics report can be made in the Construction Mode of the metrics report, in the Report list.

Ordinary (Simple and Multiple Report)

Normalized (Cross Parameter Report)

Distributed

Averages

Ordinary (Simple and Multiple Report)

You can use Ordinary reports to view the values of a single or multiple metrics parameter for a group of objects of observation.

You can select a single parameter to view in the report. The independent values of the single series in the report are the elements of observation (particular functions or modules). A series is defined by the value of the parameter specified for the specified element of the object of observation (the specified object of observation is a group of modules). The scope of values accepted has been defined, and values outside the accepted scope can be marked.

Parameters expressed in percentages (Executable lines, Preprocessor statements...) are obtained by dividing the real values by the number of lines of code or by the number of statements in the code.

Minimal and maximal accepted values for a particular parameter can be set in the Options > Software Metrics Calculator dialog box.

For the level of observation of a group of modules, each parameter represents the total parameter value in modules over selected objects of observation. Border values are obtained by multiplying the values specified by the number of objects of observation. For example, if the object of observation is a group of 3 modules, the upper accepted border value for the parameter Lines being 1000, the maximal accepted value for the parameter Lines will be 3000.

The types of charts which can be applied to the Simple report are Bar, Column, and Table.

Metrics Simple Report

Simple report

Normalized (Cross Parameter Report)

You can use Cross parameter reports to view the values of several metrics for a group of objects of observation. This type of report, just like the Simple report type, aims to display the real values of metrics, but has the additional possibility of displaying simultaneously several different metrics. In other words, you get several Simple reports in one and the same chart.

For each metrics parameter selected, a data series with as many values as there are selected objects of observation (functions, modules) is formed.

Parameters expressed in percentages (Executable lines, Preprocessor statements...) are obtained by dividing the real values by the number of lines of code or by the number of statements in the code.

In order to display several disparate metrics in the same chart, the values obtained must be normalized, considering specified border values (set in the Options > Software Metrics Calculator dialog box). Values below 10% point to the parameter value having exceeded the minimal specified value, while values over 100% point to the parameter having exceeded the maximal specified value. Unacceptable values (those which exceed the minimal/maximal specified value) can be visually separated from the acceptable values.

For the level of observation of a group of modules, parameters are obtained as totals of parameter values in modules; these totals are then normalized in the 10-100% interval.

The types of charts which can be applied to Cross parameter reports are Bar, Column, Radar, and Table.

Figure bellow shows a Radar chart for four different parameters with several series, one for each of the functions observed.

Metrics cross parameter report

Cross parameter report

Distributed

You can use Distribution reports to view the distribution of the values of a single metrics parameter within the specified scope of values.

This type of report can only be created for a single selected parameter. As a result, these reports have a single data series. The values of the selected metrics parameter for each of the objects of observation will be sorted by intervals. The scope of acceptable values is set in the Options > Software Metrics Calculator dialog box. A scope set in this manner will be divided into five equal intervals, plus an additional interval for those parameter values which are instances of overflow or underflow of acceptable parameter values.

For each of the intervals, the number of times a value of the specified parameter appears in the specified interval in the object of observation is displayed. The number of appearances is expressed in percentages in relation to the total number of appearances. Intervals within the acceptable scope of parameter values differ visually from intervals outside that scope.

Figure bellow shows a report of the Distribution type, in the form of a Pie chart. For example, the parameter viewed is the parameter McCabe Cyclomatic complexity for which the specified scope of acceptable values ranged from 0 to 10. Displayed are the intervals for values ranging from 0 to 2, from 2 to 4, from 6 to 8, from 8 to 10, and for values exceeding 10. The selected object of observation is a group of 12 functions, of which 2 functions have parameter values ranging from 2 to 4. For this interval, 16.7% is displayed (2/12).

The types of charts which can be applied to a Distribution report are Bar, Column, Pie and Table.

Metrics Distribution report

Distribution report

Averages

Average reports give you the mean values of one or more metrics over a group of selected objects of observation.

If several parameters have been selected to be displayed, the obtained mean values will be normalized to allow for parallel viewing. In this way, apart from a simple view of mean values for a specified parameter, you can view the comparative relations of metrics (for example, the mean value of the number of clean comment lines in relation to the mean value of the number of lines with comment).

Parameter values are obtained by totaling individual parameter values for each of the objects of observation. Parameters expressed in percentages (Executable lines, Preprocessor statements...) are obtained by dividing these totals by the total number of lines of code or the total number of statements in the code. Values thus obtained are normalized, considering specified border values (set in the Options > Software Metrics Calculator dialog box).

Values below 10% point to the parameter value having exceeded the minimal specified value, while values over 100% point to the parameter having exceeded the maximal specified value. Unacceptable values (those which exceed the minimal/maximal specified value) can be visually separated from the acceptable values.

The types of charts which can be applied to Average reports are Bar, Column, Radar, and Table.

Figure bellow shows an Average report, shown in the form of a Column chart.

Metrics Average Report

Average report

Types of Metrics Reports by Presentation

The following sections give a detailed description of individual ways of visualizing metrics reports.

Bar Chart

Column Chart

Pie Chart

Radar Chart

Table

Bar Chart

A bar chart is made up of a series of horizontal rectangles. Each data series is marked in a different color, and it is possible to choose between seven different styles for viewing. A legend with a brief explanation of each series can be displayed in the report. The report can be sorted according to a series or according to the names of the objects of observation.

It is possible to display any type of metrics report by means of a Bar chart.

Figure bellow displays a Cross parameter metrics report in the form of a Bar chart with five series.

Metrics cross parameter report bar chart

Bar chart

Column Chart

A Column chart is made up of a series of vertical rectangles. Its other attributes are identical to those of a Bar chart.

Each data series is marked by a different color, and it is possible to choose between seven different styles for viewing. A legend with a brief explanation of each series can be displayed in the report. The report can be sorted according to a series or according to the names of the objects of observation.

It is possible to display any type of metrics report by means of a Column chart.

Figure bellow shows a Simple metrics report in the form of a Column chart, with a single series and a large amount of data, displayed in its entirety in the Metrics window by means of the Fit to Window option.

Metrics Simple Report Column chart

Column chart

Pie Chart

A Pie chart appears as a number of circular segments, each of which represents an interval of the parameter value. A single series is allowed, and there are two colors for viewing, representing values in the acceptable and unacceptable scope, to choose from.

A Pie chart can be selected only for Distribution metrics reports.

Figure bellow shows a Pie chart with values in the unacceptable scope marked red.

Metrics Pie Chart

Pie chart

Radar Chart

A Radar chart appears as a group of dots on the radial axes and lines which connect values in the same series. Each series is represented by a broken line in one of the seven possible styles. A legend with a brief explanation of each series can be displayed in the report.

A Radar chart can be selected for Cross parameter and Average metrics reports.

Figure bellow shows a Cross parameter metrics report in the form of a Radar chart with five parameters displayed for several functions viewed.

Metrics Radar Chart

Radar chart

Table

Table view is a table which displays the values of a single or multiple data series in a column. Acceptable and unacceptable property values are displayed in different colors. A table can be sorted according to data by clicking the column header. The visibility of values in the table can be improved by selecting the Grid and Stripes options. A table is the only view which has the possibility of displaying the decimal part of property values. The other types of charts display rounded off parameter values. Values can be displayed with an accuracy of six decimal places.

Figure bellow shows a Cross parameter report in the form of a table (in Construction Mode) with nine modules viewed.

Metrics Cross Parameter Report Table

Working with Metrics Reports

This chapter describes the details of working with metrics reports and actions frequently performed upon them.

Selecting Objects

You can select certain parts of a metrics report by clicking. After a selection has been made, the specified object is drawn in a different color and its edges become thicker. The selection can be cancelled by clicking another object, or the empty space of the metrics report.

Selecting certain values of a data series allows you to sort the metrics report according to the data in that series. Selecting names of modules or of functions allows you to sort the report according to names, or to select a new object of observation for metrics reports.

Using the Shortcut Menu

Right-clicking one of the values displayed in a metrics report opens the shortcut menu. Depending on the selected level of observation for the metrics report, the contents of the shortcut menu will be as follows:

Level of Observation for a Group of Modules

The shortcut menu displays the names of the modules selected in the object of observation. Clicking one of the names opens an Editor with the selected module.

Level of Observation for a Single Module

For Simple and Cross Parameter reports, the shortcut menu displays all the functions of the selected module. For Distribution reports, the shortcut menu displays all modules whose parameter values are within the specified scope. For Average reports, the shortcut menu displays all modules selected in the object of observation. Clicking one of the names opens an Editor with the selected module or function.

Function Level of Observation

For Simple and Cross parameter reports, the shortcut menu is identical to that in the Editor and pertains to the function selected. Choosing a command from the menu opens the corresponding window (Editor, Browser, Graph, or the Metrics window) which displays the content you wanted.

For Distribution reports, the shortcut menu displays all functions whose parameter values are within the specified scope. For Average reports, the shortcut menu displays all functions selected in the object of observation. Clicking one of the names opens an Editor with the selected function.

Tooltips

When you hold the insertion point over a parameter value displayed in a chart, a tooltip appears, displaying the series to which the value belongs (if there are several series), and the rounded off numerical value. A more exact value (rounded off to the number of decimal places you have specified) can be viewed in Table chart.

Closing the Metrics Report

Once created, a metrics report is considered a part of the active metrics template and can be completely removed only by means of the Metrics > Remove report command. Closing the Metrics Report window in some other way only removes the metrics report from the desktop area. A temporarily removed metrics report can be displayed again by selecting it from the LRU list of the Metrics menu.

Copying the Metrics Report to the Clipboard

You can copy an active metrics report to the Clipboard by means of the Edit > Copy command. The report will be copied in WMF (Windows Metafile Format) for Bar, Column, Radar, and Pie chart types of view. For Table view, RTF (Rich Text Format) will be used.

Thanks to this possibility, metrics reports can be worked on in graphics programs or spreadsheet programs.

Saving the Metrics Report

You can save an active metrics report by means of the File > Save As command. The Save As dialog box will appear with a suggestion for naming the file in which the report will be saved. Reports of the Bar, Column, Radar, and Pie type are saved in WMF format. Data from Table view can be saved either in RTF or TXT format; the latter will be in tab-delimited form.

The suggested file name is identical to the title of the window of the metrics report you want to save, with the addition of the appropriate extension.

Printing the Metrics Report

You can print a metrics report by means of the File > Print command. Before doing this you can take a look at the preview of the metrics report by means of the File > Print Preview command.

As with the other windows in DAC, you can choose between mosaic and fit-to-page printing.

The dimensions of the printed metrics reports can be set in the Metrics > Options dialog box. In this dialog box, report dimensions can be set in physical units (inches, millimeters), so that printing is guaranteed to be consistent with the specified dimensions. The metrics report appears proportionally scaled on the screen considering the specified report dimensions.

A legend containing precise explanations of particular data series can appear on the printed metrics report.


Copyright 1993-2017, RistanCASE GmbH