Contents > 8 Defining Custom Design Metrics and Rules > 8.1 Definition of Metrics > 8.1.8 Element Comparisons
8.1.8 Element Comparisons
The procedure compare performs pairwise comparisons of model
elements. Consider the following example:
<metric name="DupNameCount" domain="class">
<description>The number of data types that have the same name as this class.</description>
<compare term="name" target="datatype" with="name" comp="term=with" />
</metric>
Evaluation of the compare procedure is as follows:
- First, we evaluate the metric expression term for the
current model element. If the term expression is missing, the
model element itself is used as comparison value.
In our example, term yields the name of the model element.
- Next, we have to specify the comparison set - the set of elements
to which the current element will be compared. We have two
alternatives to do this:
- By specifying attribute set with a set expression that is
evaluated for the current element. The resulting set must be an
element set. Each element in the set can be subjected to the usual
filters (target, element, eltype, condition, targetcondition, scope).
- Alternatively, we can omit the set attribute, and only
specify the target attribute instead. The attribute must then
indicate one model element type, and the current element will be
compared to all model elements of that type.
In the above example, the comparison set is the set of all datatype
elements.
- Next, we iterate over each element in the comparison set:
- For each element, we evaluate the with expression. Again,
if no with expression is specified, the model element itself
is used as comparison value.
In the above example, the expression yields the name of the data type.
- We then take the results from the term and with
expression, and use these to evaluate the comp expression.
This is a condition expression specifying the comparison to perform.
Within the comp expression, the values of the term
and with expression are denoted by the identifiers "term" and
"with", for example comp="term!=0&term>=with". If no
comp expression is specified, the values are tested for
equality (i.e., "term=with").
In the above example, the comparison expression yields true for all
data types with the same name as the current class.
- We add up the number of elements for which the comp
expression evaluates to true. The total is the value of the
metric.
In the above example, the result of the metric is the number of data
types that have the same name as the current class.
The following example shows the use of the set attribute and
skips the with and term expressions. The metric
counts, for a class, the number of inner classes that have more
methods than the class itself. In the example we assume that
- metric NumMth is the number of methods of a class,
- set InnerClasses is the set of inner classes of a class.
<metric name="BiggerInnerCls" domain="class">
<description>The number of inner classes that have more methods than the class itself.</description>
<compare set="InnerClasses" comp="term.NumMth<with.NumMth" />
</metric>
There are two more optional attributes which control the behavior of
the compare procedure:
- return_element - takes values "true" or "false". When set
to false (the default), the metric value is the number of elements for
which the comp expression evaluates to true. When set to
"true", the metric returns an arbitrary model element in the
comparison set for which the comp expression is true, or an
empty string if no such element exists.
- exclude_self - takes values "true" or "false". When set
to true (the default), the current element will not be compared to
itself even if it is contained in the comparison set. Set to false if
you want this comparison to take place.