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.
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.
You can always find the newest version of this page at: http://www.kclee.com/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.
-
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).
-
100% Pure Java.
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 17.35
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 javancss17.35/lib/javancss.jar, javancss17.35/lib/ccl.jar, and javancss17.35/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 javancss17.35 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.
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.
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:
Also if the control flow of a method returns abortively the CCN value will
be incremented by one:
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 17.35
Version 17.35 has been released on April 14, 2002...
What's New
- Javadocs are now also displayed on a package level.
Fixed Bugs
- Javadocs were mistakenly counted for attributes as well.
This bug has been crept in with the last version.
Version 16.34
Version 16.34 has been released on April 7, 2002Recursive 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, 2001New -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, 2001Major 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, 2001Optional 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, 2001Minor 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, 2001Minor 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, 2001Minor improvements.
What's New
- JAVANCSS_HOME in javancss.bat is now set automaticly.
- '-check' option to trigger self tests from command line.
Bugs Fixed
- 'super((InputStream)null,null)' gets parsed successfully
now.
Version 9.24
Version 9.24 has been released on October 4, 2000Fixed a small Java parser bug.
What's New
- No new features.
Bugs Fixed
- Fixed a small Java parser bug reported by Ramon Felciano.
Version 8.23
Version 8.23 has been released on July 1, 2000Javadoc 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, 2000Published 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, 1998More 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, 1998More 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, 1998Some 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, 1998Just 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, 1998New 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, 1998What'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
- 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.
- Last not least thanks to Metamata and Suntest for the JavaCC parser generator.
- 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).
- Ted Leung for a patch for the -out option.
- Steve Jernigan for an Ant task fro JavaNCSS. This can be
downloaded from http://sourceforge.net/projects/javancss2ant/.
- 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.
- Jonathan Doughty for the error report of JavaNCSS not being able to handle JDK 1.4 assertions.
Related Links
-
Clemens' Java Page - Other Java stuff I did.
-
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.
-
RSM, C & C++ Code Quality and
Metrics Tool - A similar tool as JavaNCSS written in C for the C language.
-
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
Private Local Links
These links are only for my private use and convenience and work only locally.
Chr.
Clemens Lahme, email to: clemens@kclee.com
(here is my resume)