Contents > 8 Defining Custom Design Metrics and Rules > 8.6 Writing Descriptions

8.6 Writing Descriptions

The measurement catalog (see Section 4.13 "The View 'Catalog'") provides detailed descriptions of the design metrics, rules, and relation matrices, complete with literature references and a glossary. These descriptions are provided by the definitions in the metric definition file.

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))
((li))Defined in ref://CK94/.
((li))See also metric://class/CLD/.
<projection relation="genchild" target="generalization" element="genparent" 
 eltype="class" nesting="true"/>

<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.

<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.
Below we explain the various features available for writing descriptions.

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.


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

In the measurement catalog display, the locator will be replaced by an HTML hyperlink that takes the user to the specified target.

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>/
In the full description as shown to the user, the locator will be replaced by a hyperlink that takes the user to the definition of the term. If the name of the glossary term and the hyperlinked text to be shown are identical, you can leave the hyperlinked text empty, like so: This is a glossary://WFR// of the UML (note the two slashes after "WFR").