JavaNCSS - A Source Measurement Suite for Java

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
• System Requirements
• Downloading
• Usage
  • XSLT Stylesheets
• Specification
• Development
• Release History
• Copyright Notice
• Credits
• Related Links
• Private Local Links

Features and Metrics JavaNCSS Provides

System Requirements

Downloading

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

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

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

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

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)

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

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)

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

• if
• for
• while
• case
• catch
• &&
• ||
• ?

Development

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

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

Release History

Version 32.53

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

Version 30.51

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

Version 29.50

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

Version 28.49

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

Javadoc bug fixed.

Fixed Bugs

1. Javadoc bug fixed, reported by Kyle Blaney.

Version 25.45

Various Java 1.5 parser bugs fixes.

Fixed Bugs

1. Various small Java 1.5 parser bugs fixes.

Version 24.44

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

Fix in Enum parser.

Fixed Bugs

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

Version 22.42

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

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

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

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

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

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

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

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

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

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

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

Minor bug fix release.

Bugs Fixed

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

Version 10.25

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

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

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

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

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

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

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

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

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

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

Copyright Notice

Credits

Authors

• Thanks to Metamata and Suntest for the JavaCC parser generator and especially the Java grammar on which JavaNCSS is based.
• Ted Leung for a patch for the -out option.
• Steve Jernigan for an Ant task fro JavaNCSS. This task can be downloaded separately from http://sourceforge.net/projects/javancss2ant/ but is distributed with JavaNCSS as well. This task has also some additional features such as checks of user defined thresholds on individual metrics.
• Pääkö for a patch for the -recursive feature [2002-03-16].
• John Wilson for a patch to use "\r\n" on Windows to end lines for JavaNCSS's ascii output.
• Emilio Gongora and Guillermo Rodriguez for patches to count number of lines of comments. Applying these patches is not finished yet and the only result you can see already is the the new Javadocs info for packages.
• Phillip Wells for working on Steve Jernigan's Ant task and submitting it to the Ant project to be added into the optional.jar file [2002-06-08].
• Ross Gardler (ross at saafe.org) 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 [2002-06-15].
• Terry Skelton (tskelton15 at attbi.com) donated an XSLT stylesheet to convert the XML output of JavaNCSS to HTML. [2002-07-05].
• Yves Coene (Yves.Coene at spacebel.be) donated XSLT stylesheets which generate beautiful SVG charts from the JavaNCSS XML output [2002-09-04].
• Rajesh Raheja (Rajesh.Raheja at oracle.com) donated an XSLT stylesheet, which generates a simple HTML report of all metrics which exceed a certain limit [2003-05-11].
• Chris Povirk for a patch in the XML handling for enums [2006-06-12].
• David Chwalisz for enhancements to the ant build.xml script [2006-10-06].
• Simon Brandhof for opening and moving JavaNCSS to the Codhaus development infrastructure (and Jira for bug tracking) [2009-02-07]. This will open up development to better collaboration with other developers and possibly will lead to new talent contributing much needed updates.
• Hervé Boutemy for moving the whole project to Maven and cleaning up all kind of code areas (encoding etc.) [2009-02-07].
• Freddy Mallet for a draft version of a new Java parser, which will allow easier extension of JavaNCSS by traversing Java source code via the visitor pattern [2009-02-07]. Hopefully this might also lead to more people being able to fix grammar bugs or updating the grammar to Java language extensions.

Thanks To

• Frans van Gool for HtmlViewer (which got replaced by JavaHelp since JavaNCSS version 7).
• Thanks to the users of JavaNCSS and to the people who provided valuable feedback and requests.
• Thanks to Glen Cordrey for the tip how to set the JAVANCSS_HOME variable automaticly in javancss.bat.
• Joseph Kiniry for bug reports for the parser and example test code (2001-06-16).
• Jonathan Doughty for the error report of JavaNCSS not being able to handle JDK 1.4 assertions.
• Carsten Lergenmüller for two error reports regarding the '-recursive' feature.
• Chris Williamson for finding a rare parsing bug having to do with inner, outer, and super classes [2002-05-11].
• Ted Leung for writing an Ant task for JavaNCSS of his own. Unfortunately I never got around looking into it and adding it to JavaNCSS. Finally when I found the time I decided to go for Steve Jernigan's task, as that adds some new features to JavaNCSS and has detailed documentation. Thought Ted's task has a simpler interface with its parameter names sticking nearer to the original JavaNCSS options [2002-06-08].
• David Brandt fixed the wrong Javadocs per Function value for XML output [2002-07-21].
• Vesa Karvonen for feedback regarding the overloaded 'functions' element in the XML DTD, which has led to the conversion stylesheet 'javancss_no_functions_overloading.xsl' [2002-08-04].
• Again Vesa Karvonen for a bug report that revealed the incorrect production of XML output in conjunction with some exotic locale setting [2002-09-03].
• Brad Kiewel for patching the build.xml Ant file to add a manifest to the javancss.jar file, so JavaNCSS can now be executed via java's -jar option [2002-09-04].
• Anthony Sobey for pointing out that the '&&', '||', and '?' statements haven't been considered for measuring cyclomatic complexity numbers [2003-12-14].
• Bill Burcham for adding SVG doctype definitions to the SVG stylesheets [2003-12-22].
• Wally Bowles for the suggestion to use 'Method' instead of 'Function'. Has been applied so far only to an optional HTML output style sheet [2004-08-08].
• Don Morrison, Lakshman Srilakshmanan, Eduardo Sherington for various bug reports [2006-05-14].
• Tom Mitchell for bug reports and test code in the Java 1.5 parser code [2006-06-12].
• Charles L, Anver Sotnikov, James Burton, Byron du Preez, Martin Lehofer, Darren M. Siegel, David Chwalisz for a bug reports and test code in the Java 1.5 parser code [2006-10-06].
• Don Kautz and Isabelle Guimiot for bug reports and test code for the Java 1.5 parser code [2008-04-08].
• Jean-Laurent de Morlhon for good morale when moving to Codehaus [2009-02-07]!
• Jovana Milutinovich for the Croatian translation of this page [2012-10-12]!

Related Links

• Clemens' Java Page - Other Java stuff I did.
• JavaNCSS - Paket za merenje izvornog Java koda is a translation of this page into Croatian by Jovana Milutinovich!
• Sonar is an open source code quality management platform. Sonar enables to collect, analyze and report metrics on source code. Sonar not only offers consolidated reporting on and across projects throughout time, but it becomes the central place to manage code quality. With no complex infrastructure, Sonar fulfills needs in terms of code quality, whether it is to make an audit or implement a continuous improvement process.
• Jacob - A development tool that embeds the Emacs editor. It can also be used as a gui-frontend for JavaNCSS.
• Clemens' PSP Page - JavaNCSS can be used as a tool for the Personal Software Process (PSP).
• JavaCC - A Java compiler compiler from SunTest. JavaNCSS is done with it.
• JDepend - Mike Clark's JDepend "traverses a set of Java source file directories and generates design quality metrics for each Java package. JDepend allows you to automatically measure the quality of a design in terms of its extensibility, reusability, and maintainability to effectively manage and control package dependencies."

  While JavaNCSS simply lets you know how much source code you have to deal with (ncss metric), JDepend informs you about the package structure of your code and helps you spotting weaknesses in your global code organization, e.g. identifying dependency cycles, creating a few independent packages on which most other package rely on, etc.

  You can use JDepend as a quantitative measurement tool as well.

• ProGuard - ProGuard is a class file shrinker and obfuscator by Eric Lafortune. It differs from other offerings in its simple and compact configuration, its speed, and its modest memory usage.

  ProGuard is an application which has made use of JavaNCSS in an unexpected way: "... I've taken the liberty of using JavaNCSS for producing test results with ProGuard, and, vice versa, for producing statistics about ProGuard. You can find the references in the Results section and the Quality section respectively. The latter section shows how I have integrated JavaNCSS in a nightly build process."

• SLOCCount is a set of tools for counting physical Source Lines of Code (SLOC) in a large number of languages of a potentially large set of programs. This suite of tools was used in a Estimating Linux's Size to measure the SLOC of an entire Linux distribution. It runs on Linux, Windows, and hopefully on other systems too. To run on Windows, you have to install Cygwin first.
• Cetus Links: Object-Orientation / Metrics