metre.doc

这是一个C程序分析工具

              int c;
           } d;
        } e;


Preprocessor Statements

As counted by Metre, a preprocessor statement is a source line that
begins with optional whitespace followed by a '#' character that is not
contained within a comment. If you run Metre against the output of a
preprocessor, most preprocessor statements will have been processed and
removed, so this count may be unusually low or even 0. The preprocessor
may pass some #pragma's through and may also insert #line statements, so
the count of preprocessor statements may have little bearing on the
number present in the original source file.

Metre does not recognize a preprocessor statement that has been
continued onto another line. It will most likely cause a syntax error
when Metre tries to parse the continued line. In this case, you must
preprocess the source first to remove all continued preprocessor
statements.


Function Points

Function points are estimated using what is known as "backfiring." It
has been determined that it takes an average of 128 C statements
(executable, declaration, and preprocessor statements) to code one
function point. This assumes moderately complex code. From Capers Jones
book, _Applied Software Measurement_,

        In essence, it takes fewer statements to implement one function
        point for simple applications than it does for complex ones.
        This concept is also true in reverse: When function points are
        backfired, highly complex code will contain fewer function
        points than the same volume of simple code. This concept is
        counterintuitive, but it appears to be empirically correct.

So, for example, if the code you are measuring contains a lot of
functions that have a high cyclomatic complexity index, such as 38, the
backfired function points that Metre generates will be a bit high--the
code actually represents fewer function points.

Note: If you run your code through the preprocessor first, the number of
preprocessor statements will likely be reduced. This then reduces the
backfired function points. However, it has been my experience that
preprocessor statements make up only a small percentage of the total
number of statements in a C program. Likewise, if your preprocessor
includes line directives, e.g., # 23 "filex.c", Metre counts them as
preprocessor statements. This also distorts the backfired function
points. So in order to get the most accurate estimates, try to run Metre
against your original source. Use the -D command-line option to perform
any needed translations in lieu of the preprocessor.

Adjusting Function Points

In the SPR's 1985 backfire method, described in Capers' book, the
initial backfired function points can be adjusted up or down based on
the combined logic, data, and problem complexities. These are subjective
metrics and use a different scale than that of cyclomatic complexity. It
has not been established in the literature how one would use cyclomatic
complexity to adjust backfired function points for a more accurate
estimate.

However, having said that, I use the following table, based on Table
2.16 in _Applied Software Measurement_, to adjust the initial
function-points metric when the -a command-line option is specified.
This is not the default behavior because my adjustment algorithm is
unsanctioned--there is no standard that I know of for adjusting function
points based on cyclomatic complexity.

I look up in this table the multiplier that corresponds to the
cyclomatic complexity and divide the initial function-points metric by
this value. I use the same range of multipliers as Capers does in his
book (0.70 - 1.30), I use the same qualities, "Simple" to "Very
complex," to characterize complexity, and I use his discussion of the
degrees of cyclomatic complexity to determine how to map them to the
appropriate multipliers. The curve of this function is asymptotic to the
1.30 multiplier; however, not truely, because I clip the factor at the
cyclomatic complexity of 54--all complexities at or above 54 have the
same multiplier of 1.30. See the graph that follows the table.

Modification of TABLE 2.16 for Cyclomatic complexity adjustment
    Cyclomatic                   Code size adjustment
    complexity                        multiplier
        1          Simple               0.70
        2                               0.80
        3          Moderate             0.85
        4-5                             0.90
        6-8                             0.95
        9-11       Average              1.00
        12-16                           1.05
        17-21                           1.10
        22-27      Complex              1.15
        28-36                           1.20
        37-53                           1.25
        54-        Very complex         1.30

Graph of Modification of TABLE 2.16 for Cyclomatic complexity adjustment
   1.30                                         .      .      .      .
                                .
   1.15                .
                  .
   1.00        .
             .
   0.85    .
          .
   0.70  --------------------------------------------------------------
          1 3  10           25                     54
     Simple   Average     Complex                  Very complex
         Moderate


Mtree Call-Tree Tool
--------------------
The set of rules in trerules.c define the tool, Mtree, that prints
call-hierarchy trees and an optional function table of contents.
Briefly, from the command line, you can name the root function, select
an alternate graphic character set for the tree or select no tree at
all, specify the width of the file-name margin, specify the degree of
indention, specify whether to print the table of contents, and select
whether to ignore library calls. Here is the help text, displayed with
the -h command-line option, that identifies the command-line options and
their function.

METRE Version 2.3  Copyright (c) 1993-1995 by Paul Long  All rights reserved.
Syntax: MTREE [ 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
-rxxx       Root function name         -cN         Indent columns per level [4]
-g          Alternate-character tree   -t          Print table of contents
-n          No tree                    -l          Ignore library calls
-mN         File name margin [12]


Basic Operation

Mtree accepts one or more C source files and prints one or more call
trees. If the name of a root function is specified on the command line
with the -r option, as in -rlog_transaction, Mtree starts the first tree
with that function. If not specified, Mtree starts with the function
named "main." If there is no main function, Mtree starts with the first
function it encounters.

Once this first call tree has been printed, Mtree prints separate call
trees for functions that have not yet taken part in a call tree. This is
especially useful for function libraries, where there is not just one
root function.

If you want Mtree to ignore calls to the Standard C library, such as to
printf(), use the -l command-line option. This is useful if you want to
consider the library as part of the language.

Mtree normally just prints the call trees and then stops. However, you
can instruct it to print a table of contents after the trees with the -t
command-line option. This lists all functions by file name along with
the line number on which they are defined. Mtree's file, function, and
line are analogous to a book's part, chapter, and page.


Formatting Command-Line Options

Use the -c command-line option to tell Mtree how many columns to indent
each call level. For example, -c8 causes Mtree to indent each level by
eight columns. The default is by four columns.

Use the -m command-line option to specify how wide the left margin is
within which Mtree prints the name of the file that contains the
function. Mtree right-justifies the file name within this margin and
truncates any extras characters to the left so that some path
information may be lost. This assures that at least the file name can be
seen. The default margin width is 12 columns (do I detect an MS-DOS bias
here?). For example, -m20 allows for a margin for potentially longer
UNIX file names. Here is a tip: Specify -m0 if you do not want the file
name in the output.

Mtree draws a "tree" to show the calling hierarchy. This graphically
connects calling functions with called functions. By default, Mtree uses
ASCII characters to draw the tree lines so that its output is
displayable on virtually all output devices. However, you can select an
alternate set of graphic characters with the -g command-line option.
This causes Mtree to use line-draw characters from the IBM graphic
character set. Trees drawn with these characters look much nicer. Many
printers, including laser printers, have a font that contains these
characters. If you want something else, change the alternate characters
in trerules.c. If you do not want Mtree to draw the tree at all, use the
-n command-line option.


Limitations

For the name of a called function, Mtree uses the identifier immediately
before the call's '('. This may give misleading results if a function is
called through an expression that yields a function pointer.

Mtree ignores duplicate function names. This should only cause a problem
if you have functions in different files with interal linkage (e.g,
static foo() { ... }) that have the same name. Mtree ignores the
second and subsequent functions with the same name.


Commercial Metrics Tools
------------------------
The only metric tool I have ever used is Metre. If you feel you need a
more robust or complete product or just want the support of a commercial
product, here are a couple of commercial metrics tools. They both
support C and C++, run under several operating systems, and cost several
hundred dollars. Metre was inspired by CodeCheck, but the rules are not
portable between the two products.

        CodeCheck
                Abraxas Software
                5530 SW Kelley Ave.
                Portland, OR 97201
                USA
                Phone: [phone]
                Fax: [phone]
                AppleLink: D2205
                MCI: ABRAXAS

        PC-METRIC
                SET Laboratories, Inc.
                P.O. Box 868
                Mulino, OR 97042
                USA
                Phone: [phone]
                Fax: [phone]
                Internet: [e-mail]


Bibliography
------------
Halstead, M., _Elements of Software Science_, Elsevier North Holland,
New York 1977.

Jones, C., _Applied Software Measurement_, McGraw-Hill, New York, NY,
1991, 493 pages.

Kitchenham, Pickardm, and Linkman, "An evaluation of some design
metrics," _Software Engineering Journal_, 5(1), January 1990, pp. 50-58.

Lassez, et al., "A critical examination of software science," _Journal
of Systems and Software_, 2, 1981, pp. 105-112.

McCabe, T., "A Complexity Measure," _IEEE Transactions on Software
Engineering_, vol. SE-12(4), December 1976, pp. 308-320.

Miller, et al., "A software science counting strategy for the full Ada
language," _SIGPLAN Notices_, 22(5), May 1987, pp. 32-41.

Munson and Khoshgoftaar, "The dimensionality of program complexity,"
_Proceedings of the 11th International Conference on Software
Engineering_, 1989, pp. 245-253.

Myers, G., "An Extension to the Cyclomatic Measure of Program
Complexity," _SIGPLAN Notices_, 12(10), October 1977, pp. 61-64.

Shepperd, "An evaluation of software product metrics," _Information and
Software Technology_, 30(3), April 1988, pp. 177-188.

Shepperd and Ince, _Journal of Systems and Software_, October (?) 1994.


Bugs
----
1. In Metre, all typedef definitions have file scope. I have never seen
anyone use block-scoped typedef definitions, so I doubt whether this
will catch anyone. Here is an example of what you cannot do:

                     typedef int a;
                     main()
                     {
                        typedef char *a;
                     }

Metre declares a syntax error at the second "a" because it thinks that
it is a type specifier, like "int," and not an identifier.

typedef scoping would not be that hard to implement. For example,
replace the current symbol table with a stack. Mark the beginning of a
new scope. Push typedef names onto the stack. Search the table from the
most recently pushed names. At the end of a scope, pop all typedef names
off up to the first-encountered scope mark.

2. Another typedef bug. You will not encounter it, though, unless you
use an identifier for a member name that is the same as a visible type
name. Luckily, programmers often use a naming convention that eliminates
this possibility. For example, if member names are always in lower case
and type names are always in upper case, this bug will never occur. As
an example of the bug, Metre declares a syntax error for the member
declaration in this code.

                     typedef int bool;
                     struct {
                        int bool;
                     } foo;

Type names have the name space as object names, so if this member
declaration appeared outside the struct as an object declaration, it
would be invalid syntax. However, member names have a unique name space
for the struct within which they are declared, so this code is
valid--the two bool identifiers should occupy different name spaces.
Unfortunately, Metre does not take the unique name spaces of structs
into consideration, hence the bug. To Metre, "int bool;" looks like "int
int;", which would of course be invalid syntax.

Only one person has reported this bug, so I will delay its fix, maybe
when I go ahead and fix the other bug by performing typedef scoping.


Possible Enhancements
---------------------
Here are some enhancements that I have thought about implementing in
Metre.

Features
- Calculate essential complexity. (Requires control-flow analysis,
        though, which is not trivial).
- Distinguish between executable and non-executable code lines in LOC
        metrics.
- Count commented-code lines.

Infrastructure
- Do not display line number for module & project messages.
- Recognize C++ comments.
- Recognize C++.
- Optionally recognize the common "asm { ... }" construct.
- Perform preprocessor file inclusion but do not accumulate metrics for
        the included source.
- Recognize preprocessor statements that are continued onto another
        line.


Trademarks
----------
Trademarks are the property of their respective owners.


Disclaimer
----------
THE METRE SOURCE AND INCLUDED ACCESSORY FILES ("THE SOFTWARE") ARE NOT
WARRANTED IN ANY WAY TO BE SUITABLE FOR YOUR SITUATION. YOU USE THE
SOFTWARE ENTIRELY AT YOUR OWN RISK.