metre.doc

这是一个C程序分析工具

beginning of this section are the names that one can use in the -m
command-line option, e.g., -mfnp. This option allows one to specify
which metrics to print. If none are specified, all are printed. If one
or more are specified, only those that are specified are printed. The -m
option can be specified more than once on the command line. For example,
-mcyc -mexc, would print only the cyclomatic and extended complexity
metrics.

The Halstead metrics are only printed when the -H command-line option is
specified. Use the -s option on the command line to only display the
summaries (module summary, and if more than one module, project
summary). In other words, this suppresses the function-specific
information.

Metre prints a warning if it encounters a goto or continue statement or
multiple return statements in a function. Metre also prints a warning if
it encounters indention accomplished by both spaces _and_ tabs.

By specifying the -h command-line option, Metre prints the following
help text which identifies the command-line options and their function.
The text also explains the output notation, such as "<min >max ~avg
total".

METRE Version 2.3  Copyright (c) 1993-1995 by Paul Long  All rights reserved.
Syntax: METRE [ option | file ]...
-Dxxx=[xxx] Define identifier          -oxxx       Name of output file
-Sxxx       Substitute file name       -C          Copy input to output
-w          Suppress warnings          -h          This help
-fxxx       Response file
-s          Summaries only             -H          Halstead metrics
-a          Adjust function points     -TN         Stroud number [18]
-c          Comma-separated value      -mxxx       Select specific metric

Notation and Abbreviations:
<           Minimum                    Cyclomatic  Cyclomatic complexity
>           Maximum                    Max Depth   Max control-structure depth
~           Average                    Exec        Executable
(nothing)   Total                      Decl        Declaration
Lang        Language                   PP          Preprocessor

For -m option: bll cyc cdl cml dcs exc exs fnc fnp inc idc idl llv mdc mcd
pef pln plv pps ptm pvl pvc scl 

If you think that some of the diagnostics Metre generates are
unreasonable, such as warning about gotos, do not worry--you can easily
change how Metre behaves by modifying the source (see the Modifying
Metre section in the accompanying install.txt file).


CSV Output

The -c option causes Metre to generate its output in
comma-separated-value format (CSV) in the same order as the above,
human-readable output. This allows the data to be more easily used by
another program or imported into a database or spreadsheet. You will
probably also want to suppress warnings with the -w option so that they
will not be interspersed with the CSV data.

All the data for each function appears on one line, all the data for
each module appears on one line, and all the data for the project
appears on one line (if present). The first field for each type of line
contains a type identifier--fcn, mod, or prj, respectively. The second
field for a function or module line is the name of the module. The third
field for a function line is the name of the function. There are no name
fields for the project line. The numeric data follows for each type of
line. There are no intervening spaces in a line. Just like the
human-readable output, the first line is always the Metre copyright
notice. Here is a shortened example of CSV output. Ellipses show data
that I have removed which is normally there.

METRE Version 2.3  Copyright (c) 1993-1995 by Paul Long  All rights reserved.
fcn,metrules.c,rules,41,67,799,154, ... ,12,4,313,2,28,10
fcn,metrules.c,print_help,1,1,92,28, ... ,0,0,31,6,21,8
fcn,metrules.c,init_project_stats,2,2,233,33, ... ,0,1,102,2,13,8
mod,metrules.c,1,50,8,1,67,9,5, ... ,426,94,25,5,2268,1,30,8,24
fcn,trerules.c,cmpstr,1,1,8,8, ... ,0,0,3,3,7,5
fcn,trerules.c,library_call,1,1,320,162, ... ,1,0,9,4,7,6
fcn,trerules.c,lookup_function,2,3,29,16,  ... ,1,1,13,4,8,6
mod,trerules.c,1,10,4,1,13,4,8, ... ,185,70,35,3,636,1,23,8,20
prj,1,50,6,1,67,7,5,1412,158,5, ... ,441,295,611,164,60,7,2904,1,30,8,44,2

The options that effect whether certain data is printed also work for
the CSV output. For example, if -H is not specified, there is no
Halstead data in the output, including the commas--there is never an
empty field, i.e., ",,".


Complexity

Metre recognizes each of these constructs as representing a single
decision point:

        conditional operator, ?:
        if statement
        while statement
        do-while statement
        for statement with a conditional expression, e.g., for (;x;)
        adjacent cases in a switch statement

There are a few situations in C where the presence of a decision point
may be debatable. Metre counts the conditional expression (?:) as a
decision point, it counts adjacent cases as one decision point, and it
counts decision points in a switch statement as if it were simulated by
a series of cascading if-then-else statements. For an example of
adjacent cases, the following switch statement contains two decision
points, not three.

         switch (a)
         {
         case 0:
            dothis();
            break;
         case 1:
         case 2:
            dothat();
            break;
         }

Metre interprets decision points in this way so as to minimally
influence the programmer's choice of constructs. If it did not count the
conditional expression as a decision point, the programmer might be
influenced to use confusing conditional expressions instead of if
statements in order to achieve a lower cyclomatic complexity. Likewise,
adjacent cases are analogous to the logical "or" operator (||). If Metre
counted each case as a separate decision point, the programmer might
avoid the switch statement in favor of an if statement with an
expression that uses the or operator. For example,

         if (a == 1 || a == 2)

McCabe's cyclomatic complexity metric works out to be the number of
decision points in a function plus one. McCabe established an upper
limit of 10. As Capers Jones says in his book, _Applied Software
Measurement_,

        Empirical studies reveal that programs with cyclomatic
        complexities of less than 5 are generally considered simple and
        easy to understand. Cyclomatic complexities of 10 or less are
        considered not too difficult. When the cyclomatic complexity is
        more than 20, the complexity is perceived as high. When the
        McCabe number exceeds 50, the software for practical purposes
        becomes untestable.

In the same book, the author describes how cyclomatic complexity is
related to maintainability. "The phrase 'bad fix' refers to an error
accidentally inserted into a program or system whle trying to fix a
previous error."  As you can see from this table, which summarizes his
exposition, highly complex programs are expensive to maintain. As
cyclomatic complexity approaches 100, your fix is more likely to
introduce another error as not.

                  Cyclomatic         Probability
                  Complexity         of Bad Fix
                  ------------------------------
                  less than 10        5
                  20-30              20
                  greater than 50    40
                  approaching 100    60

A general concern I have with counting decision points in a switch
statement (also known as a case statement) comes from the comment that
McCabe makes in a footnote in "A Complexity Measure." He says that, "For
the CASE construct with N cases use N-1 for the number of conditions.
Notice, once again, that a simulation of case with IF's will have N-1
conditions." I do not understand this and have not found anyone who can
explain it to me. I assume he is referring to a case statement in a
language unfamiliar to me where all possible values _must_ be tested. In
that case, one of the tests would be analogous to the final "else" if
the case statement were simulated with cascading if-then-else
statements.

Glenford Myers defined an extension to McCabe's cyclomatic complexity
metric (although McCabe anticipated it). In addition to counting the
same decision points as McCabe, he counts compound decisions. In C,
these are constructed with logical operators and adjacent cases. For
example,

   foo() {
      if (a == b && c == 0)
         x;
   }

would have a cyclomatic complexity of 2 but an extended complexity of 3.
Myers would even write this as 2:3. Metre counts logical operators
wherever they occur in a function, not just in control-flow statements.
For example, the logical operators in the following assignment
statement are counted.

   a = b || c && d == e;

With Myers' extended complexity, cases each count as one, regardless of
whether they are adjacent. For example,

   foo() {
         switch (a)
         {
         case 0:
            dothis();
            break;
         case 1:
         case 2:
            dothat();
            break;
         }
   }

has a cyclomatic complexity of 3 and an extended complexity of 4, or 3:4.


Halstead Metrics

Metre considers the following lexemes as operators for the Halstead
metrics.

        Keywords:
                break case continue default do else for goto if return
                sizeof switch while

        Operators:
                ( [ . -> ++ -- , sizeof & * + - ~ ! / % << >> < > <= >=
                == != ^ | && || ? : = *= /= %= += -= <<= >>= &&= ^= ||=
                ; { ...

                (Basically, all operators except '}', ')', and ']'
                because the paired tokens, such as '(' and ')', are
                considered to be one operator.)

Metre considers these as operands for Halstead.

        Identifiers
        Typedef type names
        Numeric constants
        Strings

Note: A label and its terminating colon are not counted because Halstead
says that labels are considered to be comments.

Declarations are not considered in computing the Halstead metrics--only
program logic. Exceptions to this are the initializers within compound
statements. Metre considers them to be logic that coincidentally appear
in declarations--they are equivalent to assignment statements.
Therefore, Metre considers the object name, the assignment operator
('='), and the initializer expression for the Halstead metrics. The
operator that terminates the expression, such as comma or semicolon, is
not considered. The assumption is that this lexeme belongs to the
declaration and not to the logic.

For example, these two functions are equivalent.

   foo()
   {
      int a = 3;
   }

   foo()
   {
      int a;

      a = 3;
   }

(The Halstead metrics are slightly different for them, however. This is
because the second function has an extra semicolon operator.)

These are the equations that Metre uses to calculate the Halstead metrics.

        Given:
                unique operators        n1
                unique operands         n2
                total operators         N1
                total operands          N2
                Stroud number           S = 18 moments / second
                seconds-to-hours factor f = 60 * 60

        Program Length                  N = N1 + N2
        Program Vocabulary              n = n1 + n2
        Program Volume                  V = N * log2(n)
        Program Level                   L^ = (2 / n1) * (n2 / N2)
        Programming Effort              E = V / L^
        Programming Time (in hours)     T^ = E / (S * f)
        Intelligence Content            I = L^ * V
        Language Level                  L' = L^ * L^ * V

A few words about notation in these equations: The circumflex character
(^) indicates an estimated measure of an observed parameter. In
Halstead's book, the circumflex appears over the symbol rather than
following it. Also, the Greek symbol, lambda, used in Halstead's book is
represented as L', above.

The Stroud number is the highest number of "moments" per second of which
humans can perceive. We cannot notice anything faster. This ranges from
5 to 20 moments per second, maybe a little less. Halstead uses 18 in his
book, _Elements of Software Science_; however, I do not know what his
rationale is for this particular value. It could have even been
arbitrary. Regardless, by default, Metre uses a Stroud number of 18 for
its calculation of Programming Time. You can specify another value with
the -T command-line option. For example, -T10 specifies a Stroud number
of 10.

Note: The Halstead metrics are not normally calculated by Metre. You
must specify the -H command-line option for them. This is because of the
extra processing required to calculate these metrics. On my machine,
calculating the Halstead metrics slows down Metre by about 25 per cent.


Line Classifications

Metre considers a line to be a blank line if it contains only whitespace
characters, a code line if it contains at least one non-whitespace
character that is not part of a comment, and a comment line if it
contains all or part of a comment and there is not also code on the
line.

Note: Metre calculates lines of comments. However, if you run your
program through a preprocessor, the preprocessor will have most likely
stripped all comments from its output. Metre cannot count what is not
there. What is the solution? Well, some preprocessors provide a
command-line option that passes comments through. If yours has this
capability, you probably want to use it.


Statement-Counting Standard

Metre uses the SPR Source Code Counting Rules described in the book,
_Applied Software Measurement_, by Capers Jones, as its guide in
deciding what language constructs are considered to be statements.
Additional clarification has been provided by Mr. Jones through private
communications regarding specifics of the C language.


Executable-Statement Definition

An executable statement, as counted by Metre, is an if, switch, while,
do-while, for, expression, goto, continue, break, or return statement.
An executable statement can also be a function definition or a label.
The "empty" statement (";") is not an executable statement.


Declaration-Statement Definition

A declaration statement is any declaration construct that ends with a
semicolon. For example, there are five declaration statements in this
example:

        struct {
           int a;
           char b;
           struct foo {