JavaNCSS Ant Task User Manual

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.com/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.