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://mats.gmd.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.
-
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.
-
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 6.19
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
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 included the swing.jar archive in the classpath.
Now for the first run type in (beeing in the javancss directory itself):
./javancss test/*.java -gui
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.
BTW if you don't want to unzip javancss6.19.zip to have access
to the documentation or so, you can use this zip file itself as a jar file and
start JavaNCSS like:
java -classpath $JAVA_HOME/lib/classes.zip:./javancss6.19.zip javancss.Main *.java
Synopsis
javancss [-option] stdin | [@]source_file*
Options
-
-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.
-
-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 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 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://mats.gmd.de/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 uses (is linked to) the HTML
browser by Frans van Gool. "It [HTML browser] can be copied and used
without charge for non-commercial purposes. When you want to use it for
commercial purposes, please contact me first." (F.v.Gool)
Credits
Frans van Gool for HtmlViewer,
Thanks to the users of JavaNCSS and to the people who provided valuable feedback and requests.
Related Links
Private Local Links
These links are only for my private use and convenience and work only locally.
Chr.
Clemens Lahme, email to: Clemens.Lahme@gmd.de
(here is my resume)