8.6 Writing Descriptions

Below is an example of a full-fledged metric description. Descriptions of rules and matrices follow the exact same scheme.

<metric name="DIT" domain="class">
<description>The depth of the class in the inheritance tree.((p))
This is calculated as the longest glossary://Path/path/ from the class to
the root of the inheritance tree. The DIT for a class that has no
parents is 0.((p))
((ul))
((li))Defined in ref://CK94/.
((li))See also metric://class/CLD/.
((/ul))
</description>
<projection relation="genchild" target="generalization" element="genparent" 
 eltype="class" nesting="true"/>
</metric>

<reference tag="CK94">S. Chidamber, C. Kemerer, "A Metrics Suite
  For Object Oriented Design", IEEE Trans. Software Eng., vol. 20, no. 6, 
  pp. 476-493, 1994.
</reference>

<term name="Path">A sequence of adjacent nodes in a graph. The
  sequence of nodes n(1), n(2), ..., n(m) is a path if there is an
  edge from n(i) to n(i+1) for all i from 1 to m-1.
<term>

HTML markup

The detailed description is meant to be rendered in HTML. Therefore, you can use HTML markups to format your text. However, because the description is embedded in an XML file, you cannot use the plain HTML tags. They would interfere with the XML structure. Instead of enclosing your HTML tags with the usual < and > brackets, use two subsequent opening and closing parentheses, like so: Text in ((i))italics((/i)) or ((b))boldface((/b)).

The example for metric DIT above uses paragraphs and bulleted lists to format the text.

Brief description and full description

The first sentence of the description should be a short definition that states the basic idea what the metric (or rule or matrix) is about. It should be brief enough to fit in a single line (about 80 characters, but that is no hard limit).

This first sentence must be terminated by a period, and must not use any HTML markup. The brief descriptions are used in various windows of SDMetrics' GUI, to provide short explanations of metrics, rules, and matrices. The description then continues with additional explanations, and notes about the metric. Together with the brief description, this constitutes the full description shown in the measurement catalog.

Cross-references

You can reference other metrics, rules, or matrices in the description.

• To cross-reference a metric, use a "metric locator" of the form metric://<domain>/<name>/. For example, to cross-reference a metric NumOps for elements of type class, write metric://class/NumOps/. Note the terminating slash at the end of the locator.
• Likewise, to cross-reference a rule, use a locator of the form rule://<domain>/<name>/. For example, rule CyclicInheritance for classes is referenced by rule://class/CyclicInheritance/.
• To cross-reference a relation matrix, use a locator of the form matrix://<matrix>/. A matrix named "Associations" would be referenced by matrix://Associations/.

Literature references

To provide literature references, you define a bibliographic citation as in the above example for metric DIT. The citation is enclosed in a reference XML element. The element has one required attribute, tag, which provides a handle for the citation.

You can then reference the citation in your metric, rule, and matrix descriptions with a locator of the form ref://<reference_tag>/, for example ((li))Suggested in ref://CK94/.((/li)). In the measurement catalog display, the locator will be replaced by a hyperlink that takes the user to the bibliographic citation of the specified reference.

Glossary terms

If your description uses any terms that you feel need additional explanation, you can define these terms in a glossary. The above example for metric DIT shows a definition for the term "Path".

The term definition is enclosed in a term XML element. The element has one required attribute, name, which is the term that is defined. You can then use the term in your description with a locator as follows:

glossary://<Name of term>/<hyperlink text>/