Overview of Questions

Q1.1: SDMetrics reports metrics to be zero when they shouldn't be. What's the matter?
Q1.2: Why are my UML design element names not displayed correctly in the element and table view?
Q1.3: During metrics calculation, SDMetrics freezes and eventually aborts with a "stack overflow" error. What do I do?
Q1.4: I exported data to multiple HTML files. Why can't my web browser display them as a frame set?
Q1.5: Calculating a set of metrics, I get an error message "No elements to calculate metrics for". How come?
Q1.6: The diagram-specific metrics for my UML design are missing from the output. What happened to them?
Q1.7: Calculating a set of metrics, I get an error message "Could not open file ", but the file is a perfectly normal XMI file. Why is that?

2. Basic SDMetrics Usage

Q2.1: Can SDMetrics create output files that preserve element names with 16-bit Unicode characters?
Q2.2: I stored my huge XMI file compressed in a zip file. Do I have to uncompress it for measurement?
Q2.3: Where's the printing feature in SDMetrics?
Q2.4: Does SDMetrics support the Object Constraint Language (OCL)?

3. Advanced SDMetrics Usage

Q3.1: I want to modify the project files (metamodel, metric definitions, XMI transformations). Where are those files?
Q3.2: What XMI parser does SDMetrics use?

4. General measurement issues

Q4.1: I measured a UML design, and now what? What am I supposed to do with those measures?
Q4.2: Is there a nominal range the metrics should be in to indicate a good system?
Q4.3: There are so many measures. Do I need them all?

Answers to the questions

Q1.1: SDMetrics reports metrics to be zero when they shouldn't be. What's the matter?
A: Most likely, SDMetrics does not properly extract some model elements from your XMI file. This happens when the UML meta model of your modeling tool deviates from the official meta models, or produces non-standard XMI. In that case, SDMetrics requires special meta model and/or XMI transformation files that are tailored to the idiosyncrasies of that particular modeling tool. Check the project files download page if there already are specialized project files for your tool. If not, contact me about it. Please enclose a small sample XMI file and ideally a screenshot of the corresponding diagram in your mail, as I do not have access to every UML modeling tool out there on the market. If you wish, you can also take matters in your own hands: Section 7 of the user manual describes how you can write your own custom project files.

Q1.2: The UML design element names are not displayed correctly in the views, only some weird goobledygook. What happened?
A: Most likely this is due to the file encoding of your XMI file. Your model element names contain characters that cannot be represented with the XMI file's file encoding. Check the manual of your UML modeling tool if it possible to specify a different file encoding for the XMI export (e.g, Unicode UTF-16). If this is not possible with your XMI exporter, you should avoid using special characters in your element names.

Q1.3: During metrics calculation, SDMetrics freezes and eventually aborts with a "stack overflow" error. What do I do?
A: You are probably analyzing an XMI file generated by Microsoft Visio with SDMetrics V1.3 or earlier. Visio sometimes creates XMI files with model elements that are their own namespace. This "loop in the containment hierarchy" causes many XMI importers to crash. The project files download page has a specialized XMI transformation file for Visio which solves the problem. Since V2.0, SDMetrics has inbuilt protection against such XMI files.

Q1.4: I exported data to multiple HTML files. Why can't my web browser display them as a frame set?
A: SDMetrics enhances the HTML frame set with XML code that allows to import all data files at once in a single operation into Microsoft Office applications. This code, however, prevents some browsers from displaying the frame set properly. Open the individual tables in the browser instead. Since SDMetrics V2.0, you can also disable the XML code generation.

Q1.5: Calculating a set of metrics, I get an error message "No elements to calculate metrics for". How come?
A: Check your filter settings: maybe you filtered all elements?
A: Check your project file settings: XMI Source File, metamodel, XMI transformations etc. correct?

Q1.6: The diagram-specific metrics for my UML design are missing from the output. What happened to them?
A: Your UML modeling tool uses a proprietary solution to store diagram layout information in the XMI file. SDMetrics currently supports diagram-specific metrics for tools supporting the Diagram Interchange format of UML2, as well as Rational Rose and compatible tools (e.g. Together, Enterprise Architect), and MagicDraw. Unless your modeling tool stores diagram information outside the XMI file (e.g. ArgoUML, Describe 6.x), there is a good chance that SDMetrics' XMI import can be customized to support diagram-specific metrics for your design tool, too.

Q1.7: Calculating a set of metrics, I get an error message "Could not open file ", but the file is a perfectly normal XMI file. Why is that?
A: This problem ocurrs with SDMetrics Versions 2.02 and earlier, running with Java 6, and is caused by file names that contain whitespaces. Move your XMI file to a directory that does not have any whitespaces in its path, and/or rename the XMI file to not include any whitespaces. Or run SDMetrics on a Java 5 or Java 1.4 JRE, or upgrade to SDMetrics 2.1.

2. Basic SDMetrics Usage

Q2.1: My UML design element names contain 16-bit Unicode characters. Can SDMetrics create Unicode output files that preserve the element names?
A: Yes. Since SDMetrics 2.1, the output file encoding is configurable, see the description of the output preferences settings in the user manual. If you are using SDMetrics 2.02 or earlier: These versions of SDMetrics create their data output files using the default character set of the Java Virtual Machine. You can specify the default character set when you invoke SDMetrics with the switch "-Dfile.encoding", for example for 16-bit Unicode:

Q2.2: I stored my huge XMI file compressed in a zip file. Do I have to uncompress it for measurement?
A: No, you can access files in a zip archive. But you have to enter the file name manually. Start the file name with 'jar:', followed by the name of the zip archive, followed by an exclamation mark '!', followed by the name of the XMI file in the archive.
For example, if your zip archive resides at /MyFiles/Design.zip and contains an XMI file /xmi/design.xmi, enter the following file name: jar:/MyFiles/Design.zip!/xmi/Design.xmi.

Q2.3: Where's the printing feature in SDMetrics?
A: There is none. Spreadsheet or statistical software packages already provide excellent support for printing, with many output formatting features for optimal results. If you need to print, simply import the data in such a package and print from there, using all the bells and whistles.

Q2.4: Does SDMetrics support the Object Constraint Language (OCL)?
A: As of yet, no. There are two aspects how SDMetrics could incorporate the OCL:

• Consider OCL expressions for the measurement of structural properties. OCL expressions as part of the UML model being analyzed contribute to the size, cohesion, complexity, and coupling of model elements containing these expressions. SDMetrics may support this in future releases.
• Use OCL to define design rules for automated checking. OCL as part of the UML standard is naturally suited to define design rules. The well-formedness rules of the UML are mostly expressed in OCL. SDMetrics does not use OCL for performance reasons. SDMetrics' design rule definitions are prescriptive, which allows for more efficient checks than OCL's declarative nature. For example, rules involving the detection of cycles in dependency graphs use a computationally optimal algorithm that could not be expressed in OCL.

Q3.1: I want to modify the project files (metamodel, metric definitions, XMI transformations). Where are those files?
Short A: You can download the latest version of the project files here.
Long A: After installation of SDMetrics, those files are contained in the SDMetrics.jar file. They are named metamodel.xml and metrics.xml for UML 1.4, metamodel2.xml and metrics2.xml for UML 2, and xmiTrans*.xml (* being a placeholder for the UML or XMI version). If you don't want to download the latest files from the web, you can use jar or your favorite zip utility to extract the files from SDMetrics.jar.

Q3.2: What XMI parser does SDMetrics use?
A: SDMetrics uses a SAX2 compliant XML parser (provided by your JRE), with a proprietary SAX event handler that processes the XML tags as specified in the "XMI Transformations" and "meta model" configuration files (see Custom XMI Import) to extract the model elements contained in the XMI file.

4. General design measurement issues

Q4.1: I measured a UML design, and now what? What am I supposed to do with those measures?
A: Good question that should be asked even before thinking about using design measurement. The resources section contains a discussion of the usefulness of design measurement, including pointers to usage scenarios and useful data analysis techniques.

Q4.2: Is there a nominal range the metrics should be in to indicate a high quality system?
A: No. From empirical studies we know that the actual relationship between design metrics and system quality is complex, and very context sensitive. Depending on factors such as overall project size, development processes, project standards, and developer experience, a metric can be an excellent quality indicator on one project, a weak quality indicator on another, and completely useless on a third project. While some metrics have been shown to be consistently good quality indicators across environments, others only work occasionally. Therefore, it is not possible to specify a nominal range for each metric, and expect this to always indicate a high quality system.

Q4.3: There are so many measures. Do I need them all?
A: Probably not. Expect some redundancy among the measures. The problem is that, a priori, it is impossible to know which measures are redundant, and this is also different from environment to environment. You can perform a dimensional analysis to identify a minimal, non-redundant set of measures tailored to your development practices.