CDOC or CMETRIC analyze C and C++ programs and generates various complexity and quality
metrics. It counts code and comments, and calculates path cyclomatic complexity.
For our simple example program "EXAMPLE.C":
[return to HomePage Contents] [backup to CMETRIC]
CMETRIC is a tool to provide a simple measure of complexity and quality of functions,
and of the overall system, in order to identify the functions most at risk during
initial debugging and during long-term maintenance. Please note that the absolute
values of the metrics calculated for each function in a system are not as important
as the relative values for each function. The purpose of CMETRIC is primarily
to identify those functions most likely to have initial and/or long-term problems.
There are no magic "right" answers, but several industry studies have resulted in guidelines
that:
- Functions should be up to 50-100 lines of source code
- Function path complexity should be up to 10-20
- Too many small functions are as hard to understand and maintain as having
too few functions that are very large;
- Counting comment-block headers, many organizations expect there to be approximately
as many lines with comments as there are code lines (because of comment blocks,
this does NOT mean that every code line should be commented);
- There should be a rough balance between the number of statements and the number
of lines with code (too few statements per code lines indicates many complex statements
requiring multiple lines; too many statements per code indicates compressed code
listings that may be hard to read);
- If opening and/or closing braces are on their own lines,
then there should be significantly fewer statements than there are lines with code (say 3/4);
Again, these are only guidelines, and there are no magic "right" answers!
[return to HomePage Contents] [backup to CMETRIC]
CDOC or CMETRIC maintains various complexity/quality counters during the parsing
of 'C' and 'C++' files. This will yield a file "EXAMPLE.CPX" containing the following:
Function vs Complexity/Quality
******************************
Path 'C' CODE CMMNT Total
COMPLXTY Stmts Lines Lines Lines
(null) 0 EXAMPLE.C 0 6 6 1 6
fahren 6 EXAMPLE1.C 1 5 7 5 14
main 14 EXAMPLE.C 3 13 18 10 28
prt_line 18 EXAMPLE1.C 3 10 9 2 13
TOTAL SYSTEM SUMMARY 7 34 40 18 61
Report sorted by Complexity/Statements/Code
Multiple version of the metric report can be produced, each one
sorted different ways. They may be sorted by:
- complexity;
- number of C statements;
- number of C code lines;
- number of comments;
- and by total number of lines.
[return to HomePage Contents] [backup to CMETRIC]
Complexity/Quality Metrics Listing Trace
CDOC or CMETRIC can be used as a learning/debug tool, since it will
cause the running COMPLEXITY/STATEMENT/CODE/COMMENT counters to be
displayed on the CLIST listing. This will yield EXAMPLE.LST which contains:
CPX CODE LINE
STMT CMT SOURCE
---------- ---- ------------------------------------------------
1 09 10 11 19
1 10 11 11 20 printf ("Centigrade to Fahren conversion");
1 10 11 11 21
2 11 12 11 22 for (count=-6; count<= 20; count++)
2 11 13 11 23 {
2 12 14 11 24 # c_temp = 10*count;
2 13 15 11 25 # f_temp = fahren(c_temp);
3 14 16 11 26 # if (c_temp>= 150) {
3 15 17 11 27 # | prt_line (c_temp, f_temp);
3 16 18 11 28 #=======break;
3 16 19 11 29 # }
3 17 20 11 30 # prt_line (c_temp, f_temp);
3 17 21 11 31 }
3 18 22 11 32 exit (0);
3 18 23 12 33 } / end of main */
The columns list COMPLEXITY/STATEMENT/CODE/COMMENT counters in the
same order they are listed in the CMETRIC output ".CPX" summary file.
This "trace" capability is just there for those who would
like to follow through some examples of how the counters are maintained,
it is not a normal "user" report.
Note that the 'C' "goto/break/continue/return" statements do NOT increase
the path complexity (since once on that particular statement the path
change must always be executed), although one could argue that the
"generic" program complexity is somehow greater. In these cases, the "path"
complexity rule shows its "roots" in the theory of test case coverage!
Again, absolute numbers are not important, it is relative numbers between
functions which helps identify those functions most likely to need attention.
[return to HomePage Contents] [backup to CMETRIC]
CDOC or CMETRIC calculates the path "cyclomatic" complexity for each function
and for the system as a whole. Cyclomatic complexity is actually a simple
but powerful measure of a programs complexity, and is now probably the
most widely used measure of program complexity.
First described by T.J.McCabe
in the 1975 SE-2(4) "IEEE Transactions on Software Engineering", it is
basically a count of the number of paths through your code. Every new function
increases the complexity by one, and every decision point (if,for,while,switch)
within a function increases the complexity by one.
For a good overview of software metrics, try the Sep94 IEEE Computer magazine
in general, and the page 18-25 "Successfully Applying Software Metrics" article
in particular.
[return to HomePage Contents] [backup to CMETRIC]
Optional "Logical" Complexity
CDOC or CMETRIC also optionally tracks "logical" complexity and adds it to
the path complexity. Thus "A && B" causes the complexity to increase by one.
Note that the reason for this is that anytime a logical operation is used within
the control portion of a logic construct (i.e. within the "if" condition, etc.),
then there is an additional situation under which the path may, or may not,
be executed. It is assumed that if there is a stand-alone logical operation,
then that logical operation is being performed so that the results can be
used by some later logic-control structure. Again, the "cyclomatic" complexity
metric show its roots in code testing and coverage analysis.
[return to HomePage Contents] [backup to CMETRIC]
There are MANY industry measures of a "statement", unfortunately there is
no common standard yet. What is important is that this number be white
space (format) independent to give a measure of the actual code content
independent of how "spaced" or "compressed" it is written.
In general, CMETRIC counts ";" statement deliminators. However, note that CMETRIC counts
int x,y;
as 2 statements (since this is really a short-hand
abreviation of 2 declarations). Also note that CMETRIC counts
if(A) B; else C;
is counted as 4 statements (1 for the "if" statement, 1 for the "true" statement, 1 for the optional "else"
statement if present, and 1 for the "false" statement):
if(A)
B;
else
C;
[return to HomePage Contents] [backup to CMETRIC]
Code Lines, Comment Lines, and Total Lines
Code Lines
A code line is any line which contain a non-blank non-comment (ie a 'C'
or 'C++' syntax element). It can be as simple as a brace "{", or as
complex as one text line which is itself part of a long multi-line statement.
Comment Lines
A comment line is any line which contains a comment. It can be
a "/*.*/" comment within code, a "/*.*/" or "//" comment at the
end of a code line, or a non-code "/*.*/" or "//" comment line.
Multi-line comments count as multiple comment lines.
Total Lines
A total line is any text line, even a blank line (ie a count of the
number of CarriageReturns in DOS/OS2/Windows or LineFeeds in Unix).
[return to HomePage Contents] [backup to CMETRIC]
[next document javTree]
SoftWare BlackSmiths Inc, 6064 St Ives Way, Mississauga ON, Canada L5N-4M1
WWW = http://www.swbs.com
eMail = email@swbs.com
Voice/Fax = (905)-858-4466
You are the 
visitor to this page. We just reset our hit-counter aug2001
MAIN WEBPAGE INDEX: (back to the main index).