JavaNCSS - A Source Measurement Suite for Java

 
 
Update 2018-03-04: there is a new git repository at https://github.com/nokia/javancss (thanks to Gergely Herenyi)

Ever wondered how many lines of code or how many classes there are in  the Sun JDK? Curious about the size of your own projects - or do you want to keep track of your work-progress. That's what JavaNCSS is for.

JavaNCSS is a simple command line utility which measures two standard source code metrics for the Java programming language. The metrics are collected globally, for each class and/or for each function.

Here is an example about what JavaNCSS prints out for the Sun JDK 1.1.5 java.* source tree (update: JDK 1.5 api source tree consists of 569'830 ncss).

JavaNCSS can optionally present its output with a little graphical user interface. To interactively select Java source files for counting, Jacob (a Java class browser and project manager) can be used for this purpose.

JavaNCSS can also be used out of an Ant build.xml script as it comes bundled with an Ant task written by Steve Jernigan. The JavaNCSS Ant Task is documented on a separate page.

You can always find the newest version of this page at: http://www.kclee.de/clemens/java/javancss/

Table of Contents

Features and Metrics JavaNCSS Provides

  • Metrics can be applied to global-, class-, or function-level.
  • Non Commenting Source Statements (NCSS).
  • Cyclomatic Complexity Number (McCabe metric).
  • Packages, classes, functions and inner classes are counted.
  • Number of formal Javadoc comments per class and method.
  • Average values are calculated.
  • Command line driven.
  • A GUI is provided for better output browsing as well as the integration of JavaNCSS in a project manager and class browser named Jacob for easy selection of input source files.
  • XML output (optional).
  • XSLT stylesheets provided for further generation of HTML, and SVG reports and as a basis for your own custom reports.
  • Ant task (written by Steve Jernigan).
  • Support for Java 1.5 syntax (generics, enums, etc.).
  • 100% Pure Java.
  • Free software (GNU GPL).

System Requirements

Java JDK >= 1.4.1

Downloading

JavaNCSS Version 32.53

Downloading Java Development Kit

JavaNCSS requires the Java Developer's Kit (JDK) Version 1.4 or above. Since you already seem to have Java source code you want to measure, I assume you already have a JDK :). If not, you can download it via web from Javasoft. Follow the link to "JDK 1.4" and download the version applicable to your environment.
 

Usage

Make sure javancss-30.51/lib/javancss.jar, javancss-30.51/lib/ccl.jar, and javancss30.51/lib/ jhbasic.jar are added to your CLASSPATH.

Then to start JavaNCSS type: java javancss.Main. As an alternative you can edit and use either the JAVANCSS.BAT or javancss file. Just change the JAVA_HOME and CLASSPATH variables according to your system. Make sure you did include the swingall.jar archive in the classpath.

Now for the first run type in (beeing in the javancss-30.51 directory itself):

./bin/javancss -gui test/*.java

or

./bin/javancss -gui -recursive test

For regression test of JavaNCSS use:

java javancss.test.JavancssTest

If no parameter is provided for JavaNCSS, standard input (stdin) is used as the input stream. Multiple java source files can be specified in the command line. If a '@' char is put in front of a file name, then not this file will be measured but its content will be interpreted as a list of Java source files that shall be counted. The '@' functionality can be used recursively inside this file as well. Wild cards are not supported yet. (If the operating system processes the command line for the program, then you are lucky. Windows doesn't do that.) Instead use something like cat *.java | javancss or type *.java | javancss. Of course, this can lead to ambiguities when mixing source files that belong to a package with files that doesn't.

If no option is given, JavaNCSS only calculates the total non commenting source statements (NCSS) of the given input.

JavaNCSS can also be used conveniently via Ant. For details have a look at the JavaNCSS Ant Task page, especially at the example at the bottom of that page. You can also have a look at the build.xml file that gets distributed with JavaNCSS itself (see "javancss" target).

Synopsis

javancss [-option] stdin | [@]source_file*

Options

-ncss
This is the default which counts total non commenting source statements and nothing else.
-package
Collects the metrics data for each package. This is the most top level view javancss offers for your projects. Take a look here what javancss prints out for the Sun JDK 1.1.5 java.* source tree.
-object
Collects the metrics data for each class/interface. For an example program output, look here.
-function
Collects the metrics data for each function. For an example program output, look here.
-all
The same as '-package -object -function'.
-gui
Opens a gui to presents the '-all' output in tabbed panels.
-xml
Output in xml and not in ascii format. Additional option '-all' is recommended.
-out file
Output goes normally to standard output, with this option an output file can be specified.
-recursive
Java file in sub directories will be parsed as well. Be careful not to get caught in an endless loops because some Unix links.
-check
Trigger JavaNCSS self test suite.
-version
Prints out the version of JavaNCSS.
-help
Prints out some basic information.

XSLT Stylesheets

JavaNCSS comes with some XSLT stylesheet (javancss-30.51/xslt/javancss2text.xsl and javancss-30.51/xslt/javancss2html.xsl). These stylesheets can be used to convert XML output from JavaNCSS to ASCII or HTML output. In case of the ASCII output this is of course quite boring and much slower as JavaNCSS creates the identical output by default anyway. But you can use this stylesheet (or any of the others shipped as well) as a starting point to have your own presentation format. You could also change sort rules (e.g. sort by NCSS) or add your own filters to the output (e.g. show only methods with NCSS greater some limit).

Assuming you have e.g. Xalan2 installed and somewhere in your path is a shell script named 'xslt' that knows how to invoke Java with the Xalan 2 main processor class (org.apache.xalan.xslt.Process), here is how you can make use of JavaNCSS' XSLT stylesheet:

cd javancss-30.51
javancss -all -xml -recursive src > example.xml
xslt -in example.xml -xsl xslt/javancss2text.xsl

Have fun. If you create a useful new stylesheet for JavaNCSS, I would be happy to get a copy of it.

SVG Output

Yves Coene <Yves.Coene@spacebel.be> has donated some XSLT stylesheets which produce beautiful SVG charts out of JavaNCSS's XML output.

Use e.g. batik as an SVG viewer and have a look at the example files in directory xslt/svg under the JavaNCSS home directory.

Here is an example SVG chart file.

Generation of SVG files is similar to using other XSLT stylesheets as described above.

Specification

Non Commenting Source Statements (NCSS)

Statements for JavaNCSS are not statements as specified in the Java Language Specification but include all kinds of declarations too.
Roughly spoken, NCSS is approximately equivalent to counting ';' and '{' characters in Java source files.

Actually, the NCSS counter gets incremented by one for each:
 
 

Examples Comment
Package declaration package java.lang;
Import declaration import java.awt.*;
Class declaration - public class Foo {
- public class Foo extends Bla {
Interface declaration public interface Able {
Field declaration - int a;
- int a, b, c = 5, d = 6;
No matter how many fields get actually declared through a comma separated list, and no matter if  these fields get actually initialized, only one statement is counted. So "int a, b, c = 5, d = 6;" gets only +1 count, not four or even six (let me know if there is good reason to count it differently).
Method declaration - public void cry();
- public void gib() throws DeadException {
Constructor declaration public Foo() {
Constructor invocation - this();
- super();
Statement - i = 0;
- if (ok)
- if (exit) {
- if (3 == 4);
- if (4 == 4) { ; }
- } else {
expression, if, else, while, do, for, switch, break, continue, return, throw, synchronized, catch, finally
Label fine : normal, case, default
 
Not counted are empty statements, empty blocks or semicolons after closing brackets. Of course, comments don't get counted too. Closing brackets also never get counted, the same applies to blocks in general.

In some cases consecutive semicolons are illegal according to the JLS but JavaNCSS still tolerates them (thought JavaNCSS is still more strict as 'javac'). Nevertheless they are never counted as two statements.

Cyclomatic Complexity Number (CCN)

CCN is also know as McCabe Metric. There exists a much hyped theory behind it based on graph theory, but it all comes down to simply counting 'if', 'for', 'while' statements etc. in a method. Whenever the control flow of a method splits, the "CCN counter" gets incremented by one.

Each method has a minimum value of 1 per default. For each of the following Java keywords/statements this value gets incremented by one:

Note that else, default, and finally don't increment the CCN value any further. On the other hand, a simple method with a switch statement and a huge block of case statements can have a surprisingly high CCN value (still it has the same value when converting a switch block to an equivalent sequence of if statements).
 

Development

JavaNCSS has been moved to Codehaus for a shared source code repository. There is also a bug tracking tool.

JavaNCSS can actually be built using Ant or Maven. To check out the latest development source code (and compile and run the regression test suite) type the following in your shell:

svn co http://svn.codehaus.org/javancss/trunk javancss
cd javancss/trunk
ant all or mvn package
You can see more details on these Maven generated development pages.

Furthermore there are a few mailing lists available for this project.  

Release History

Version 32.53

Fixed bugs JavaNCSS-9, JavaNCSS-12, JavaNCSS-13, JavaNCSS-14, 15, 16, JavaNCSS-17, 18, 19, 20, 21, and 22.

Big thanks to Sébastien Reynaud for difficult Java grammar patches and Hervé Boutemy for applying them as well as adding his own fixes to close all bugs listed above. Follow the bug reports for more people supporting us with reports and patches!

Version 31.52

Fixed bugs JAVANCSS-10 and JAVANCSS-4. Added options to see the parse tree in debug mode as well as a new experimental Java 1.5 grammar parser, also intended to use for debugging purposes.
Note that this version requires Java 1.5.

Version 30.51

Version 30.51 has been released on February 7, 2009

Project has been moved to Codehaus using public Subversion repository and Maven project structure. Thanks to Hervé Boutemy and Simon Brandhof!

Version 29.50

Version 29.50 has been released on April 8, 2008

Fixed two Java 1.5 grammar parser bugs. Thanks to Don Kautz and Isabelle Guimiot!

Version 28.49

Version 28.49 has been released on October 6, 2006

Various Java 1.5 grammar parser bugs fixed.

What's New

  1. New "ant test" task. Use "ant check" as before for JavaNCSS self testing, thought.

Fixed Bugs

  1. Various Java 1.5 grammar parser bugs fixed.

Version 27.48

Version 27.48 has been released on July 25, 2006

Javadoc bug fixed.

Fixed Bugs

  1. Javadoc bug fixed, reported by Kyle Blaney.

Version 25.45

Version 25.45 has been released on May 14, 2006

Various Java 1.5 parser bugs fixes.

Fixed Bugs

  1. Various small Java 1.5 parser bugs fixes.

Version 24.44

Version 24.44 has been released on April 24, 2006

Fix in method counter in Java 1.5 grammar code.

Fixed Bugs

  1. Fix in method counter in Java 1.5 grammar code, detected by Don Morrison.

Version 23.43

Version 23.43 has been released on April 23, 2006

Fix in Enum parser.

Fixed Bugs

  1. Fix in Enum parser, reported by Don Morrison.

Version 22.42

Version 22.42 has been released on April 16, 2006

Java 1.5 support.

What's New

  1. Support for all new language features in Java 1.5.
  2. A new XSLT stylesheet 'javancss2methodhtml.xsl' proposed by Wally Bowles to drop the words Function and to use the word Method instead.

Version 21.41

Version 21.41 has been released on September 6, 2002

SVG charts can be generated with new XSLT stylesheets.

What's New

  1. Ives Coene donated XSLT stylesheets which generate beautiful SVG charts from the JavaNCSS XML output.
  2. The javancss.jar file contains now a manifest file that lets JavaNCSS execute via java's -jar option. The build.xml file has been updated accordingly. Thanks to Brad Kievel for this patch.
  3. Additional XSLT stylesheet that copies a standard JavaNCSS XML output file and replaces the overloaded 'functions' tags with names that are different for different elements.

Fixed Bugs

  1. Javadocs per Function always had a wrong value in the XML output. Thanks to David Brandt for fixing this.
  2. Vesa Karvonen found a rare bug in the XML output which reveals itself only in conjunction with some exotic locales.

Version 20.40

Version 20.40 has been released on July 5, 2002

Two new XSLT stylesheets, one of them to convert the JavaNCSS XML output to HTML.

What's New

  1. Terry Skelton donated an XSLT stylesheet to convert the XML output of JavaNCSS to HTML. The report is formatted to have a similar look to other common ANT reports (changelog, jdepend, etc.).
  2. Ross Gardler donated an XSLT stylesheet to convert the XML output of JavaNCSS to a format very close to HTML. This can be used to generate custom HTML pages for your project.

Version 19.39

Version 19.39 has been released on June 8, 2002

Ant task written by Steve Jernigan.

What's New

  1. JavaNCSS has now bundled the Ant task from Steve Jernigan. This task also provides some additional features as checking metrics for defined thresholds. Thanks also to Phillip Wells who worked on polishing source code and documentation of that task.

Version 18.38

Version 18.38 has been released on May 11, 2002

Fixed a rare parsing bug.

Fixed Bugs

  1. Could not parse accessing an element of the parent class of the outer class in an inner class, or in other words: could not parse this code:

Version 17.37

Version 17.37 has been released on May 4, 2002

Javadocs metric on package level and example XSLT stylesheet.

What's New

  1. Javadocs are now also displayed on a package level thanks to a patch by Emilio Gongora and Guillermo Rodriguez.
  2. XSLT stylesheet to convert XML output to ascii output. This is identical to the output you could get directly from JavaNCSS and much slower, but can be used as a basis for your own output format or to produce HTML output instead text.

Fixed Bugs

  1. Javadocs were mistakenly counted for attributes as well. This bug has been crept in with the last version.
  2. In some rare circumstances -recursive gave out a wrong "File not found" error message, thought it still processed all files correctly.
  3. "File not found" error message was only presented for the last missing file and not for all of them.

Version 16.34

Version 16.34 has been released on April 7, 2002

Recursive feature, support of JDK 1.4 assert statements.

What's New

  1. Paako Hannu provided code to recursively parse all Java files including those in subdirectories.
  2. JavaNCSS supports now JDK 1.4 assert statements. At the same time methods or variables of name 'assert' are still parsed successfully, JavaNCSS is just not able to accept a field of type 'assert' anymore.
  3. John Wilson provided code to use "\r\n" on Windows to end lines for JavaNCSS's ascii output. You might be able to turn this behavior off by overwriting the line.separator system property when invoking the Java virtual machine.

Version 15.32

Version 15.32 has been released on November 21, 2001

New -out option.

What's New

  1. New option -out to specify output file. By default std out is used. Patch was supplied by Ted Leung.
  2. An Ant task for JavaNCSS has been published by Steve Jernigan at http://sourceforge.net/projects/javancss2ant/.
  3. A basic Ant build.xml file gets distributed together with JavaNCSS. This file should be fine to compile the Java source files, but is not enough to create the jar file nor to compile the grammar with JavaCC.

Bugs Fixed

  1. When relative files are given JavaNCSS will now take the user.dir property in account to locate a file.

Version 14.31

Version 14.31 has been released on June 16, 2001

Major XML format bug fix.

Bugs Fixed

  1. XML format for object section was not well formed (missed closing objects tag).
  2. Missing newline after total printout of ncss.

Version 13.30

Version 13.30 has been released on June 14, 2001

Optional xml output.

What's New

  1. Output in xml format of collected data. Use option -xml (and recommended -all) at the command line and the metric results will be formatted in xml for further processing with xslt (e.g. to create a web page) or for importing in other applicatons. A dtd is distributed as well.

Bugs Fixed

  1. Added 'strictfp' keyword to Java grammar.

Version 12.27

Version 12.27 has been released on March 27, 2001

Minor bug fix release.

Bugs Fixed

  1. Failure to parse 'this( name, o, (String)null, array );' as the first statement in a constructor.

Version 11.26

Version 11.26 has been released on March 23, 2001

Minor bug fix release.

Bugs Fixed

  1. Failure to parse 'this.var = x;' as the first statement in a constructor.

Version 10.25

Version 10.25 has been released on March 21, 2001

Minor improvements.

What's New

  1. JAVANCSS_HOME in javancss.bat is now set automaticly.
  2. '-check' option to trigger self tests from command line.

Bugs Fixed

  1. 'super((InputStream)null,null)' gets parsed successfully now.

Version 9.24

Version 9.24 has been released on October 4, 2000

Fixed a small Java parser bug.

What's New

  1. No new features.

Bugs Fixed

  1. Fixed a small Java parser bug reported by Ramon Felciano.

Version 8.23

Version 8.23 has been released on July 1, 2000

Javadoc comments for methods are now counted.

What's New

  1. Javadoc comments for methods are now counted. The output for functions has a metric JVDC, which indicates if this method is formally documented or not.

Version 7.21

Version 7.21 has been released on January 31, 2000

Published now under the GNU General Public License.

What's New

  1. Javancss is now distributed under the GNU General Public License.
  2. Upgraded to JavaCC 1.1.

Version 6.19

Version 6.19 has been released on November 12, 1998

More tolerant towards parser errors.

What's New

  1. Javancss now continues with parsing the next source file after coming across a parse error.
  2. Exit return code (1 or 0).
  3. Moved to javax swing convention (swing 1.1 beta 3).

Version 6.18

Version 6.18 has been released on July 28, 1998

More tolerant towards parser errors.

What's New

  1. Javancss now continues with parsing the next source file after coming across a parse error.
  2. Exit return code (1 or 0).

Version 5.16

Version 5.16 has been released on July 24, 1998

Some weird input gets now accepted by the parser and a CCN counting bug got fixed.

What's New

  1. Added self test. Start it with: java javancss.test.JavancssTest

Bugs Fixed

  1. Cyclomatic Complexity Number takes now return and throw statements into account.
  2. Ctrl-Z at the end of a source file will be accepted now.
  3. <EOF> at the end of a one line comment ('//') will be accepted now.
  4. Empty statements that javac accepts but are not allowed according to the Java Language Specification are now parsed without exception.
  5. Parse error messages were sometimes not very meaningful. This was a bug, not a missing feature.
  6. '-gui' command line option was implemented but not displayed with '-help' command.

Version 4.10

Version 4.10 has been released on March 8, 1998

Just a minor bug fix version.

Bugs Fixed

  1. Swing and AWT components where mixed which resulted in some small layout problems. The GUI frontend is now tested with Swing 1.0.1.

Version 3.9

Version 3.9 has been released on February 17, 1998

New is a GUI frontend. Additionally the project manager Jacob (http://www.kclee.com/clemens/jacob/) now includes the full functionality of JavaNCSS, which makes selecting Java source files much more convenient.

What's New

  1. New '-gui' option, which is equivalent to '-all' and presents the output in it's own window instead of <stdout>.
  2. You need swing in order to get this new feature working, though command line mode still works without it.
  3. New Jacob feature: a file with absolute file names of all Java source files for the current project gets generated when creating a new makefile. Its name is the project name plus '.srcfiles.txt' as postfix and will be located in the current project directory. This file can be further used by JavaNCSS in batch mode.
  4. The above feature can be used from the command line when specifying an '@' char in front of its file name. Then JavaNCSS interprets each line of its contents as the name of a java source file that should be counted. This also works recursively and normal source file names can be intertwined with '@' files as well.
  5. New Jacob feature: 'NoEmacs' flag for Jacob's initialisation file and '-noemacs' startup option for use without an editor. This feature is planned solely for JavaNCSS users who don't want to use Jacob for programming purposes.

Fixed Bugs

  1. Methods of anonymous classes are now presented with its class information.

Version 2.4

Version 2.4 has been released on January 24, 1998

What's New

  1. New '-package' option.
  2. When <stdin> is used for input and a parse error occurs the last class and method successfully parsed is given together with the error message. Note, that errors in package or import statements or not captured this way.
  3. More documentation about what is "exactly" measured.
  4. The grammar is now slightly more tolerant, but still not as tolerant as Sun's javac compiler. I made javancss just as tolerant as necessary to parse Sun's original java.* source files.
  5. Different options can be specified and all get executed, therefor only one run is needed for different output formats.
  6. New '-all' option is equivalent to '-package -object -function'.

Bugs Fixed

  1. 'default' keyword did increment the CCN counter, but it shouldn't.

Version 1.2

Version 1.2 has been released on May 7, 1997

Copyright Notice

JavaNCSS is free software distributed under the GNU General Public License. Copyright Chr. Clemens Lee.

Credits

Authors

The currently active crew with permission to write into the source code repository can be found here [2009-02-07].

Thanks To

Related Links


Chr. Clemens Lee, email to: clemens@kclee.de,   also for JavaNCSS related communication feel free to use one of the appropriate mailing lists.