QD Metrics User Manual

Version 1.01, 2004/05/27

http://www.wrotniak.net/works/qdmet/index.html


Legal stuff: although the author has taken more than reasonable care to assure that the program works exactly as documented below and does not cause any damage, he assumes no responsibility, express or implied, for any results of use, misuse, or inability to use this software.


Contents

  1. What is QDMet?
  2. How to run QDMet
  3. Command line arguments and switches
  4. The program log
  5. Metrics generated
  6. Bonus: Graphic representation of results
  7. Distribution and support
  8. Version history

1. What is QDMet

QD Metrics (or just QDMet) is a program for quick-and-dirty metrics of C++ source code. It does not try to measure the code complexity or other non-trivial aspects   just the size.

In addition to lines of code (whatever that means), QDI generates a number of other, similar metrics which may be of use in determining a project size. These metrics are discussed in detail in one of the next sections of this document.

The program runs only under Windows: an flavor from 95 to XP.

2. How to run QDMet

QDMet is a command-line program. You run it from the command-line interface, passing to the program a number of arguments and switches following a pattern like

qdmet name=value name=value /switch name=value /switch ...

where the order of named arguments and switches does not matter.

When executed like this, QDMet scans all source files following a given naming pattern in a given directory (possibly with subdirectories to any nesting depth), generates the metrics, and produces a tabular report to the screen, and in a test file named "qdmet.log" in the directory from which it was run.

The program does not modify any of your files; this means that it is not capable of doing any harm, regardless of the way you may use or misuse it.

3. Command line arguments and switches

Each argument is of a form "name=value" (important: no spaces around '=' !!!); an argument with a given name may appear at most once in the list.

Examples:

qdmet /s root=../develop/bxlib files=*.cpp;*.h

qdmet root=c:\src\xproj /s

qdmet /s

4. The program log

QDMet generates a log/report file named qdmet.log in the directory from which it was run (not the scanned root directory). Each line of the log contains a set of metrics for one unit or a subtotal for a given directory; the grand total is given at the end.

By "unit" we understand here any number of files in the same whose names differ only in extensions. For example, files "foo.cpp" and "foo.h" will be listed as one unit, "foo", unless they are in different directories.

5. Metrics generated

Additionally, three derivatives of the above are listed (only in the log file, not in the screen output):

  • Number of comment lines per line of code;
  • Fraction of empty lines among all lines;
  • Terminators (semicolons) per code line;
  • Characters per code line.

Actually, these four my say something on the coding style, and it is quite interesting to compare them between programmers.

Remarks:

  1. If a line contains both code and comment, it will be counted in both line categories. Thus, the code

    x = sin(t+0.0001); // safety margin

    will be counted the same way as

    x = sin(t+0.0001);
    // safety margin

  2. In character count, any leading and trailing spaces are stripped from the line, and multiple spaces are merged. For example, the line

       x = z   +   t  -  1;     // ???

    will result in the same character count as

    x = z + t - 1; // ???

    but _not_ in the same as

    x=z+t-1;//???

    This prevents the worst possible abuse of gaming the system; a better approach (which I may consider in a future version) may distinguish between "meaningful" and "non-meaningful" space, so that the third example would yield identical result as the others.

  3. Code lines containing just one character are counted as empty lines. This removes a great dependency of line counting on code layout preferred by various programmers. For example, the snippet

    if (x>0)
    {
       callCounter(x);
    }

    will be counted as two code lines, the same as

    if (x>0)
       callCounter(x);

    Of course, this does not remove all layout style dependency: the fragment

    if (x>0) callCounter(x);

    will still be counted as one code line.

6. Bonus: Graphic representation of results

QDMet is a text-only program   it satisfies a relatively simple need, and I have more interesting things to do than spiffying a trivial application with GUI bells and whistles.

Still, you can view the graphic representation of the reports with use of my other freeware program, the Statmaster (check my Web site for a download).

The easiest way to integrate both programs is to place them in the same directory, together with the StatMaster setup file for QDMet reports, "qdmet.stm.ini" (included in this distribution). Run QDMet as usual, and then execute

statmaster qdmet.stm.ini qdmet.log

to view some distributions and scatter-plots of the generated metrics. Refer to the StatMaster documentation on how the setup can be modified to fit your needs and preferences.

7. Distribution and support

QDMet is free to use for anyone except Osama bin Laden. Shareware and freeware vendors may include it in their collections as long as the whole original archive, including this document, is in the package.

Updates (new features, bug fixes) are available at the QDMet Home Page, where you can also find my email address.

Although the program is supplied on the "as is" basis, I will be glad to receive feedback: problem reports and enhancement suggestions. On the other hand, I am not planning to expand the program into advanced complexity metrics areas; there are commercial offerings (and quite expensive, too) which do that. Therefore keep your suggestions not too ambitious :)

8. Version history

1.00 2003/11/24 — Original public release.

1.01 2004/05/27 — Handles read-only files.