The Measure
element defines the semantics of a single measure.
From a technical standpoint, a measure is merely a mapping between the information provided by the Data Provider and known Squore elements.
Base Measures only define the measure name and identifier,
whereas Derived Measures define how they are computed from other measures.
A Measure without computation is a base measure. The following two examples show how the SLOC
(Source Lines Of Code)
base measure and the COMR
(Comment Rate) derived measure are defined:
<Measure measureId="SLOC" targetArtefactTypes="APPLICATION;FILE" defaultValue="1" /> <Measure measureId="COMR" defaultValue="0"> <Computation stored="true" targetArtefactTypes= "APPLICATION;FOLDER;FILE;FUNCTION;CLASS;PROGRAM" result="(CLOC+MLOC)*100/(SLOC+CLOC)" /> </Measure>
The attributes allowed for the Measure
element are as follows:
measureId
is the unique identifier of the measure,
as used in the properties files[1].
targetArtefactTypes
is the type of artefact targeted by the measure.
It is one or more of APPLICATION, FOLDER, FILE, CLASS, PROGRAM, FUNCTION, or any other type defined for your project.
excludingTypes
allows refining targetArtefactTypes to exclude certain types that may have been included via an alias. You can for example specify that a metric exists for all JAVA types excet for JAVA_INTERFACE with the following syntax:
<Measure measureId="TEST_COVERAGE" defaultValue="-1"> <Computation targetArtefactTypes="PACKAGES;JAVA" excludingTypes="JAVA_INTERFACE" result="IF(IS_DP_OK(JACOCO),TST_COV,-1)" /> </Measure>
defaultValue
sets the default value to be used if no value is found for this metric.
usedForRelaxation
indicates that the measure is used in this model to indicate whether an
artefact is relaxed of excluded. Note that only one measure in your model can use this attribute.
stored="true|false" (optional, default: true)
defines whether a base measure's value is stored in the database (true) or discarded (false) after an analysis.
toolName
is the name of the tool, e.g. FINDBUGS, SQuORE, CPPTEST.
toolVersion
is the tool version used to generate the data, e.g. 1.3.9, 7.2.10.34.
The attributes allowed for the Computation
element are as follows:
targetArtefactTypes
is the type of artefact targeted by this definition. It is one or more of
APPLICATION, FOLDER, FILE, CLASS, PROGRAM, FUNCTION, or any other type defined for your project.
stored="true|false" (optional, default: true)
defines whether a derived measure's value is stored in the database (true) or discarded (false) after an analysis.
result
specifies how the measure is computed from other metrics values.
Identifiers used in the result are measureIds, and the syntax is described in Chapter 5, Computation Syntax.
The measure defined is then used with its identifier, prefixed with B.
for base measures, or prefixed with D.
for derived measures. The following example shows the use of a derived measure for a computation:
<Computation targetArtefactTypes="APPLICATION;FOLDER;FILE;CLASS;FUNCTION" result="(D.MET_OKR+D.RULE_OKR)/2" />
Tip: Inheritance
Analysis models support inheritance and overriding of metrics according to the following rules:
If a metric is defined twice for a type, the first definition takes priority for this artefact type. An INFO message is displayed in the Validator to inform you that a definition is overriden by another one.
A metric definition for a specific type overrides a metric definition for a more generic type (typically an alias).
As a result, the following definitions are allowed in your Bundle.xml
:
Specifying a different computation for one sub-type
<ArtefactType id="MODULES" heirs="FUNCTION" /> <ArtefactType id="FUNCTION" heirs="C_MODULES;PHP_MODULES;JAVA_MODULES" /> <Measure measureId="VG" defaultValue="1"> <Computation targetArtefactTypes="MODULES" result="CCN+TERN+OREL+ANTH+CABL-(CASE+DEF)" /> <Computation targetArtefactTypes="PHP_MODULES" result="CCN+TERN+OREL+ANTH" /> </Measure>
Overriding a computation imported from another file by specifying it before the file import
<?xml version="1.0" encoding="UTF-8"?> <Bundle xmlns:xi="http://www.w3.org/2001/XInclude"> (...) <Measure measureId="COMR" defaultValue="0"> <Computation targetArtefactTypes="CODE" result="IF(ELOC+CLOC=0,-1,(CLOC+MLOC)/(ELOC+CLOC))" /> </Measure> <xi:include href="../../Shared/basic_definitions/comr.xml" />