C Code Source Metrics - tool to gather simple metrics from C code (C++ will hopefully be supported in the future).

CCSM is built as an LLVM tool. clang does the heavy lifting of parsing the C/C++ into an AST, then CCSM processes the AST to gather the metrics.

Some of the metrics are very straight forward (and arguably may not be particularly useful) by themselves, for example the count of the number of 'if' conditions. Other metrics are built on these, such as the McCabe cyclomatic complexity measure.

The aim is to also include metrics in order to support the set specified by HIS.

Output is hierachial - for example, the metrics relating to each function are output and the metrics for a file will include the functions relating to the functions within that file. A global wrap-up provides a top-level overview of all files.

Output can be in the form of CSV or TSV (ideal for processing) or a more human readable 'tree' form:

Global
Files: 1
Functions: 2
IF statements: 6
ELSE statements: 4
FOR loops: 1
RETURN statements: 3
WHILE loops: 1
SWITCH statements: 1
CASE statements: 4
DEFAULT statements: 1
LOGICAL AND operators: 0
LOGICAL OR operators: 1
TERNARY operators: 1
GOTO statements: 1
LABEL statements: 2
Variables: 5
Return points: 2
Statements: 113
File: src\1.c
        Functions/Methods: 2
        Functions: 2
        IF statements: 6
        ELSE statements: 4
        FOR loops: 1
        RETURN statements: 3
        WHILE loops: 1
        SWITCH statements: 1
        CASE statements: 4
        DEFAULT statements: 1
        LOGICAL AND operators: 0
        LOGICAL OR operators: 1
        TERNARY operators: 1
        GOTO statements: 1
        LABEL statements: 2
        Variables: 5
        Return points: 2
        Statements: 113
        Function: main
                IF statements: 3
                ELSE statements: 1
                FOR loops: 0
                RETURN statements: 2
                WHILE loops: 0
                SWITCH statements: 0
                CASE statements: 0
                DEFAULT statements: 0
                LOGICAL AND operators: 0
                LOGICAL OR operators: 0
                TERNARY operators: 0
                GOTO statements: 1
                LABEL statements: 2
                Variables: 0
                Return points: 1
                Statements: 27
                McCabe: 4
                Modified McCabe: 4
        Function: vain
                IF statements: 3
                ELSE statements: 3
                FOR loops: 1
                RETURN statements: 1
                WHILE loops: 1
                SWITCH statements: 1
                CASE statements: 4
                DEFAULT statements: 1
                LOGICAL AND operators: 0
                LOGICAL OR operators: 1
                TERNARY operators: 1
                GOTO statements: 0
                LABEL statements: 0
                Variables: 1
                Return points: 1
                Statements: 86
                McCabe: 12
                Modified McCabe: 9

Some of the metrics reported have 2 variants - one based on examination of the parsed code after preprocessor expansion and the other examining the unexpanded code.

Take for example:

#define CHECK_FOR_ERROR( _val ) do { if( _val >= 0 ) { error(); } } while( 0 )
void some_function( int neg_value )
{
    CHECK_FOR_ERROR();

The fragment of some_function in the above code does not contain any 'if' tokens until the CHECK_FOR_ERROR macro is expanded.

Due to the fact that some people like to treat macros as a form of encapsulation and don't want the contents of macros counting towards function metrics while other people do, CCSM provides metrics for both where practical, allowing the user to pick and choose.

Before starting, please ensure that you have a command-line version of git installed. If you are using Windows, you must ensure that git is available to Windows Command Prompt.

To build the project you will need to be able to compile Clang. See the instructions. Currently I use Visual Studio 2013 for builds.

Follow the instructions up to the point where you have checked out Clang, then open the file llvm\tools\clang\tools\CMakeLists.txt and add the following lines:

set(CCSM_DIR F:\\WORK\\GIT\\CCSM\\)
add_subdirectory(${CCSM_DIR}\\SRC ${CMAKE_CURRENT_BINARY_DIR}/ccsm)

You will need to modify the path to point to wherever your clone of the CCSM project is, but note that

1. The path in the first line should point to the 'src' subdirectory of the clone
2. Path separators either need to be escaped (using double backslashes instead of single backslashes)

After that, follow the remainder of the instructions for building Clang. CCSM should be build as part of the complete Clang build.

TODO: Needs to be updated

The MCCABE and RAW_MCCABE metrics are based on the McCabe method of calculating cyclomatic complexity.

Cyclomatic complexity is defined for each module to be e - n + 2, where e and n are the number of edges and nodes in the control flow graph, respectively. [...] Cyclomatic complexity is also known as v(G), where v refers to the cyclomatic number in graph theory and G indicates that the complexity is a function of the graph.

Modified McCabe, where switch statements are counted as opposed to each individual case statement are also supported via MCCABE_MOD and RAW_MCCABE_MOD.

Statement counting is based on the definition provided in the C language specification, namely

"A statement specifies an action to be performed"

Syntactically it is defined as:

statement: labeled-statement compound-statement expression-statement selection-statement iteration-statement jump-statement

The following are not counted as statements, as they do not result in any operation being performed:

• Compound statements, as by themselves they serve only as a method of creating a block.
• Null statements (consisting of just a semi-colon)
• Declarations
• Labels

Statement counting is frequently used as an indication of how complex the task being implemented by the code is, hence counting the above items may skew this in some situations (e.g. source code containing a significant number of null statements could skew the metric while not actually resulting in any actions)

CCSM provides the STMT_CNT metric to report the number of statements found in the parsed C code and RAW_STMT_CNT to report the number of statements found in the raw source. Note that as the raw source code has not been pre-processed, there are times when parsing of the code will be ambiguous, for example:

#define A unsigned
...
A var;

Once expanded, the above is clearly a declaration, as compared to:

#define A x =
...
A var;

which, once expanded, is not a declaration.

Currently each macro usage is counted as a single statement statement. In some cases this will distort the statement counting unnecessarily, however not counting macro usages at all would most likely under-represent the complexity of the code in most cases, hence this seems to be the lesser of the two evils. An option to inhibit this functionality could be added in future.

Considering the following code snippet:

unsigned local_var;

unsigned adder( unsigned x, unsigned y );

unsigned subber( unsigned x, unsigned y );
{
    unsigned ret_val;
    if( y > x )
    {
        ret_val = 0;
    }
    else
    {
        ret_val = x-y;
    }
    return ret_val;
}

It's clear that local_var is file-scope and should be counted as such in the metrics. It's also clear that the body of the subber function belongs to that function (as opposed to being file scope) and should be counted as such. What's less clear is how the declaration of adder and the prototype for subber should be counted. Do these count as being function scope or file scope?

By default CCSM will:

• Count declarations within file-scope metrics
• Cound the prototype associated with a definition within the function-scope metrics.

The second behaviour may be modified via command line parameter:

• --prototypes-are-filescope will prevent the prototype of functions from counting towards function metrics; it will, instead, be included in the file-level metrics

Other tools are available which analyse C code for metrics. It's possible that the results for some of the metrics will vary slightly between the tools.