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.
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.
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).
100% Pure Java.
Free software (GNU GPL).
System Requirements
Java JDK 1.1.6 or higher
Swing 1.0.2 or higher if you want to see the output in a gui
window. Otherwise you can use JavaNCSS without Swing.
Downloading
JavaNCSS Version 21.41 If
you want to get notified when new updates for JavaNCSS are available please
press the following button:
(thanks for
your interest)
Downloading Java Development Kit and Swing
JavaNCSS requires the Java Developer's Kit (JDK) Version 1.1.6 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.1" and download the version applicable to your
environment.
You don't need Swing if you simply want to use JavaNCSS in
command line (batch) mode.
Swing is a part of the Java Foundation
Class library which will be part of the next JDK 1.2. Swing can be downloaded
from Javasoft's Developer
Connection (requires membership). If you don't have a password yet,
you can get it for free there.
Usage
Make sure javancss21.41/lib/javancss.jar, javancss21.41/lib/ccl.jar, and javancss21.41/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 javancss21.41 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 (javancss21.41/xslt/javancss2text.xsl and javancss21.41/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:
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 {
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:
if
for
while
case
catch
Also if the control flow of a method returns abortively the CCN value will
be incremented by one:
return
throw
An ordinary return at the end of method (no matter if it's a function or a procedure)
will not be counted.
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).
The first article about this trivial software metric is one of the most
cited papers in computer science. Sometimes you just must be the first
to point out some basic shit and you are history. It seems just like a
wonder that nobody was able to package Lines of Code in a more scientific
manner. Now it's too late to label someone's name on it :).
Release History
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
Ives Coene donated XSLT stylesheets which generate beautiful
SVG charts from the JavaNCSS XML output.
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.
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
Javadocs per Function always had a wrong value in the XML
output. Thanks to David Brandt for fixing this.
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
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.).
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
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
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
Javadocs are now also displayed on a package level thanks
to a patch by Emilio Gongora and Guillermo Rodriguez.
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
Javadocs were mistakenly counted for attributes as well.
This bug has been crept in with the last version.
In some rare circumstances -recursive gave out a wrong
"File not found" error message, thought it still processed
all files correctly.
"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
Paako Hannu provided code to recursively parse all Java files
including those in subdirectories.
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.
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
New option -out to specify output file. By default std out is
used. Patch was supplied by Ted Leung.
An Ant task for JavaNCSS has been published by Steve Jernigan
at http://sourceforge.net/projects/javancss2ant/.
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
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
XML format for object section was not well formed
(missed closing objects tag).
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
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
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
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
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
JAVANCSS_HOME in javancss.bat is now set automaticly.
'-check' option to trigger self tests from command line.
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
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
Javancss is now distributed under the GNU General Public
License.
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
Javancss now continues with parsing the next source
file after coming across a parse error.
Exit return code (1 or 0).
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
Javancss now continues with parsing the next source
file after coming across a parse error.
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
Added self test. Start it with:
java javancss.test.JavancssTest
Bugs Fixed
Cyclomatic Complexity Number takes now return and throw
statements into account.
Ctrl-Z at the end of a source file will be accepted now.
<EOF> at the end of a one line comment ('//') will be
accepted now.
Empty statements that javac accepts but are not allowed
according to the Java Language Specification are now parsed
without exception.
Parse error messages were sometimes not very meaningful.
This was a bug, not a missing feature.
'-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
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
New '-gui' option, which is equivalent to '-all' and
presents the output in it's own window instead of <stdout>.
You need swing in order to get this new feature working,
though command line mode still works without it.
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.
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.
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
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
New '-package' option.
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.
More documentation about what is "exactly" measured.
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.
Different options can be specified and all get executed,
therefor only one run is needed for different output
formats.
New '-all' option is equivalent to '-package -object
-function'.
Bugs Fixed
'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
Additional 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 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 donated an XSLT stylesheet to convert
the XML output of JavaNCSS to HTML. [2002-07-05].
Yves Coene
donated XSLT stylesheets which generate beautiful
SVG charts from the JavaNCSS XML output [2002-09-04].
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].
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.