<?xml version="1.0" ?>
<notes>
The following sections provide details for some of
the collected function and file metrics.
Although the metrics collected by <em>CScout</em> are considerably
more accurate than those collected by programs that either
do not parse the source code or parse the preprocessed code,
they still employ approximations.

<h2>Metrics Common to Files and Functions</h2>
<dl>
<dt>Number of C preprocessor directives</dt><dd>See <a href="#note1">note 1</a>.</dd>
<dt>Number of processed C preprocessor conditionals (ifdef, if, elif)</dt><dd>See <a href="#note1">note 1</a>.</dd>
<dt>Number of defined C preprocessor function-like macros</dt><dd>See <a href="#note1">note 1</a>.</dd>
<dt>Number of defined C preprocessor object-like macros</dt><dd>See <a href="#note1">note 1</a>.</dd>
<dt>Number of preprocessed tokens</dt><dd>Although during preprocessing whitespace is considered a valid token, this metric does not take whitespace tokens into account.
This makes it easy to compare the number of preprocessed tokens with the number
of compiled tokens.
The two metrics are equal if no macro expansion takes place.</dd>
<dt>Number of compiled tokens</dt><dd>See <a href="#note1">note 1</a>.</dd>
</dl>

<h2>File-Specific Metrics</h2>
<dl>
<dt>Number of statements</dt><dd>This
metric measures number of statements parsed while processing the file,
including statements generated by macro expansion.
See <a href="#note1">note 1</a>.</dd>
<dt>Number of defined project-scope functions</dt><dd>See <a href="#note1">note 1</a>.</dd>
<dt>Number of defined file-scope (static) functions</dt><dd>See <a href="#note1">note 1</a>.</dd>
<dt>Number of defined project-scope variables</dt><dd>See <a href="#note1">note 1</a>.</dd>
<dt>Number of defined file-scope (static) variables</dt><dd>See <a href="#note1">note 1</a>.</dd>
<dt>Number of complete aggregate (struct/union) declarations</dt><dd>
Also includes complete declarations without a tag.
See <a href="#note1">note 1</a>.</dd>
<dt>Number of declared aggregate (struct/union) members</dt><dd>See <a href="#note1">note 1</a>.</dd>
<dt>Number of complete enumeration declarations</dt><dd>See <a href="#note1">note 1</a>.</dd>
<dt>Number of declared enumeration elements</dt><dd>See <a href="#note1">note 1</a>.</dd>
<dt>Number of directly included files</dt><dd>
This counts the number of header files that were directly included while processing the project's source files.  If each file is processed exactly once, the metric is roughly similar to the number of #include directives in the project's files.
See also <a href="#note1">note 1</a>.</dd>
</dl>

<h2>Function-Specific Metrics</h2>
<dl>
<dt>Number of statements or declarations</dt><dd>Nested statements are counted recursively.
Thus
<fmtcode ext="c">
while (a)
	if (b)
		c();
</fmtcode>
counts as three statements.
<dt>Number of operators</dt><dd> See <a href="#note2">note 2</a>.</dd>
<dt>Number of unique operators</dt><dd>
See <a href="#note2">note 2</a>.</dd>
<dt>Number of if statements</dt><dd> See <a href="#note3">note 3</a>.</dd>
<dt>Number of else clauses</dt><dd> See <a href="#note3">note 3</a>.</dd>
<dt>Number of switch statements</dt><dd> See <a href="#note3">note 3</a>.</dd>
<dt>Number of case labels</dt><dd> See <a href="#note3">note 3</a>.</dd>
<dt>Number of default labels</dt><dd> See <a href="#note3">note 3</a>.</dd>
<dt>Number of break statements</dt><dd> See <a href="#note3">note 3</a>.</dd>
<dt>Number of for statements</dt><dd> See <a href="#note3">note 3</a>.</dd>
<dt>Number of while statements</dt><dd>This metric does not include the <code>do .. while</code> form.
 See <a href="#note3">note 3</a>.</dd>
<dt>Number of do statements</dt><dd> See <a href="#note3">note 3</a>.</dd>
<dt>Number of continue statements</dt><dd> See <a href="#note3">note 3</a>.</dd>
<dt>Number of goto statements</dt><dd> See <a href="#note3">note 3</a>.</dd>
<dt>Number of return statements</dt><dd> See <a href="#note3">note 3</a>.</dd>
<dt>Total number of object and object-like identifiers</dt><dd>Also includes macros.</dd>
<dt>Number of unique object and object-like identifiers</dt><dd>Also includes macros.</dd>
<dt>Number of global namespace occupants at function's top</dt><dd>
This metric measures the namespace pollution in the object namespace
at the point before entering a function.
Its value is the count of all macros as well as objects with
file and project-scope visibility that are declared at the point it
is measured.
See <a href="#note1">note 1</a>.
See <a href="#note4">note 4</a>.
</dd>
<dt>Number of parameters</dt><dd>See <a href="#note1">note 1</a>.</dd>
<dt>Maximum level of statement nesting</dt><dd>
In order to avoid excessively inflating this metric when measuring
sequences of the form
<fmtcode ext="c">
if (a) {
	...
} else if (b) {
	...
} else if (c) {
	...
} else
	...
}
</fmtcode>
this metric does not take into account the nesting
of <code>else</code> clauses.
Thus the above code will be given a nesting level of 1,
rather than 3, which is implied by the following
(actual) reading of the code.
<fmtcode ext="c">
if (a) {
	...
} else
	if (b) {
		...
	} else
		if (c) {
			...
		} else
			...
		}
</fmtcode>
See <a href="#note1">note 1</a>.
See <a href="#note4">note 4</a>.
</dd>
<dt>Fan-in (number of calling functions)</dt><dd>
This is also listed under a function's details for functions
that are not defined (and have not metrics associated with them).</dd>
<dt>Cyclomatic complexity (control statements)</dt><dd>
This metric, <em>CC<sub>1</sub></em> measures the number of branch points in the function.
In order to avoid misleadingly high values that occur from
even trivial <code>switch</code> statements, this metric
measures the complexity of a <code>switch</code> statement as 1.
</dd>
<dt>Extended cyclomatic complexity (includes branching operators)</dt><dd>
This metric, <em>CC<sub>2</sub></em>, takes into account the nodes introduced by the Boolean-AND,
boolean-OR, and conditional evaluation operators.
</dd>
<dt>Maximum cyclomatic complexity (includes branching operators and all switch branches)</dt><dd>
This metric, <em>CC<sub>3</sub></em>, considers each <code>case</code> label as a separate node.
</dd>
<dt>Structure complexity (Henry and Kafura)</dt><dd>
This metric is calculcated as follows.<br />
<em>C<sub>p</sub></em> = (<em>fan_in</em> * <em>fan_out</em>)<sup>2</sup>
</dd>
<dt>Halstead volume</dt><dd>
This metric is calculcated as follows.<br />
<em>HC</em> = (<em>number_of_operators</em> +
<em>number_of_operands</em>) *
log<sub>2</sub>(
<em>unique_number_of_operators</em> +
<em>unique_number_of_operands</em>)<br />
Where operands are object identifiers, macros,
numeric and character constants.
For the purpose of determining unique operands,
each numeric or character constant is considered
a separate operand.
</dd>
<dt>Information flow metric (Henry and Selig)</dt><dd>
This metric is calculcated as follows.<br />
<em>HC<sub>p</sub></em> =
<em>CC<sub>1</sub></em> *
<em>C<sub>p</sub></em>
</dd>
</dl>

<h2>Notes</h2>
<dt><a name="note1">Note 1</a></dt><dd>
This metric is measured the first time a file is encountered in a project.
The metric does not take into account regions that were not processed
due to conditional compilation.
</dd>

<dt><a name="note2">Note 2</a></dt><dd>
This metric is calculated before preprocessing, so as to account
operators occuring in function-like macros to the corresponding macro.
However, this makes it difficult to differentiate between commas used
to separate function arguments and the comma operator.
As a result the comma is ignored as an operator.
</dd>

<dt><a name="note3">Note 3</a></dt><dd>
This metric is calculated before preprocessing, so as to account
keywords occuring in function-like macros to the corresponding macro.
As a result C keywords used during preprocessing as identifiers,
as in
<fmtcode ext="c">
#define x(if, while, else) (if + while + else)
</fmtcode>
will be miscounted as keywords occuring in the corresponding
macro.
Furthermore keywords generated during preprocessing, as in
<fmtcode ext="c">
#define WHILE(x) while(x) {
#define WEND	 }

WHILE (x)
	foo();
WEND
</fmtcode>
will not be counted as occuring in the corresponding C function.
</dd>

<dt><a name="note4">Note 4</a></dt><dd>
This metric is not measured for function-like macros.
</dd>

</notes>
