JavaNCSS Ant Task

Description

Checks some basic code metrics and generates a report.

This task wraps the JavaNCSS library for determining code metrics. The library determines several code metrics such as class counts, non-commented source statements (NCSS), cyclomatic complexity numbers (CCN), and javadoc statements. These counts are subtotaled per function, class, and package.

This task can generate a report (in plain text or XML format) and allows you to place minimum and maximum thresholds on each metric. All metrics are included for completeness, however some will be more useful than others.

Note on use: Several empirical studies have shown that more complexity leads to more defects. The metrics calculated by this task can be used to focus review and indicate opportunities for refactoring. Such a proactive approach to development will increase quality through design improvements, easier testing, and reduction of defects.

The ant verbose option will cause information on each object checked to be displayed. The default package is indicated by a "." in messages.

The set of files to be adjusted can be refined with the includes, includesfile, excludes, excludesfile and defaultexcludes attributes. Patterns provided through the includes or includesfile attributes specify files to be included. Patterns provided through the exclude or excludesfile attribute specify files to be excluded. Additionally, default exclusions can be specified with the defaultexcludes attribute. See the section on directory based tasks for details of file inclusion/exclusion patterns and their usage.

This task forms an implicit FileSet and supports all attributes of <fileset> (dir becomes srcdir) as well as the nested <include>, <exclude> and <patternset> elements.

This Ant task for JavaNCSS has been written by Steve Jernigan with support from Phillip Wells and is located at SourceForge: http://sourceforge.net/projects/javancss2ant/.
The home page of JavaNCSS is located at: http://www.kclee.de/clemens/java/javancss/.

Parameters

There are three kinds of parameter: those related to report generation, those related to threshold checking and those common to both.

Common parameters

Attribute Description Required
srcdir The location of the Java source files to be analysed. Yes
includes comma separated list of patterns of files that must be included. All files are included when omitted. No
includesfile the name of a file. Each line of this file is taken to be an include pattern No
excludes comma separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. No
excludesfile the name of a file. Each line of this file is taken to be an exclude pattern No
defaultexcludes indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. No
abortOnFail If true, the build will be terminated if a threshold is exceeded. If false, only a warning message is printed. Default is false. No

Report generation parameters

Attribute Description Required
generateReport Whether a report should be generated. Default is false. When set to true, the report will be created in the location specified by 'outputfile', or to the standard output if this parameter is not set. No
outputfile The fully-specified path of the report to be created by this task. If omitted and 'generateReport' is set to 'true' the report will be sent to the standard output. No
format The format of the report. Allowable values are 'plain' and 'xml'. 'plain' is the default. No
packageMetrics Whether metrics data for each package should be included in the report . Default is true. No
classMetrics Whether metrics data for each class/interface should be included in the report . Default is true. No
functionMetrics Whether metrics data for each function should be included in the report . Default is true. No

Threshold checking parameters

Attribute Description Required
classPerPkgMax Set the maximum threshold for the classs per package metric. This is an integer option. No
classPerPkgMin Set the minimum threshold for the classes per package metric. This is an integer option. No
ncssPerPkgMax Set the maximum threshold for the NCSS per package metric. This is an integer option. No
ncssPerPkgMin Set the minimum threshold for the NCSS per package metric. This is an integer option. No
funcPerPkgMax Set the maximum threshold for the functions per package metric. This is an integer option. No
funcPerPkgMin Set the minimum threshold for the functions per package metric. This is an integer option. No
classPerClassMax Set the maximum threshold for the inner classes per class metric. This is an integer option. No
classPerClassMin Set the minimum threshold for the inner classes per class metric. This is an integer option. No
funcPerClassMax Set the maximum threshold for the functions per class metric. This is an integer option. No
funcPerClassMin Set the minimum threshold for the functions per class metric. This is an integer option. No
ncssPerClassMax Set the maximum threshold for the NCSS per class metric. This is an integer option. No
ncssPerClassMin Set the minimum threshold for the NCSS per class metric. This is an integer option. No
jvdcPerClassMax Set the maximum threshold for the javadoc statements per class metric. This is an integer option. No
jvdcPerClassMin Set the minimum threshold for the javadoc statements per class metric. This is an integer option. No
jvdcPerFuncMax Set the maximum threshold for the javadoc statements per function metric. This is an integer option. No
jvdcPerFuncMin Set the minimum threshold for the javadoc statements per function metric. This is an integer option. No
ccnPerFuncMax Set the maximum threshold for the CCN per function metric. This is an integer option. No
ccnPerFuncMin Set the minimum threshold for the CNN per function metric. This is an integer option. No
ncssPerFuncMax Set the maximum threshold for the NCSS per function metric. This is an integer option. No
ncssPerFuncMin Set the minimum threshold for the NCSS per function metric. This is an integer option. No

Examples

   <taskdef name="javancss"
            classname="javancss.JavancssAntTask"
            classpath="${CLASSPATH}"/>

   <javancss srcdir="${build.src}"
            abortOnFail="false" ccnPerFuncMax="10"
            includes="**/*.java"/>
    

Checks for functions with a greater than 10 CCN from the java source files and prints a warning message for each instance. Even if a function exceeds the threshold, the build is allowed to continue.

   <taskdef name="javancss"
            classname="javancss.JavancssAntTask"
            classpath="${CLASSPATH}"/>

   <javancss srcdir="${build.src}"
            generateReport="true"
            outputfile="${test.results.root}/javancss_metrics.xml"
            format="xml"/>
    

Creates an XML-format report called javancss_metrics.xml in the directory specified by ${test.results.root} on all source files in the directory specified by ${build.src}. No thresholds are checked.


Copyright © 2001-2002 Steve Jernigan <sjernigan@iname.com>, distributed under the GNU General Public License (GPL).