Javaanal: Java documentation assessment utility

Purpose

This utility lets a project manager assess how well-documented a suite of Java software is, and to repeat that assessment as often as required during the life of the project. Javaanal takes the output from Sun's JavaDoc utility (a set of HTML files) and analyses its content to tell you:

• how many classes, interfaces, methods, etc, there currently are in your project
• how well-documented the code is

Environment

Javaanal is written in Visual Basic 5.0 (sorry), and will run under Win95 or 98, and possibly NT.

Javaanal assumes that you have used JavaDoc (rather than any other Java documentation package) to generate a set of HTML files describing your project. JavaDoc works by stripping out specially-formatted comments from your code, and incorporating them into a framework that it creates from your code's structure.

Javaanal will not work properly if your source code comments are in any language other than English, although it will work happily with both US and International English.

Use

To use Javaanal, first get JavaDoc to generate your HTML files, then run Javaanal and give it the directory that holds the HTML files, and the name of an output file.

Javaanal looks at the files in the directory, and picks out any that start with "Package" - it assumes that these are the top-level package descriptions for the packages in your project. It will then drill down into the other HTML files as it comes across references to them in the package documentation.

Javaanal provides two forms of output - on the screen it will generate a single "percent complete" figure that indicates how your project is going. The output file is comma-delimited (suitable for opening with Excel, etc), and gives stats on each package as follows:

• pname: name of this package
• ninterfaces: number of interfaces defined for this package
• ninterfacemethods: number of methods defined in all of this package's interfaces
• nclasses: number of classes in this package
• nclassmethods: number of methods defined in all of the classes in this package
• nclassconstructors: number of constructors for all classes in this package
• nclassvariables: number of variables used in all of the classes in this package
• commonwords: number of times the words "the", "and", "for" or "to" appear in the documentation for this package (used to calculate the documentation index)
• percentcomplete: the number of words of documentation actually found, as a percentage of the number of words required (using the metrics below)

The number of words of documentation actually required are estimated by the utility at:

• 200 words for each interface
• 50 for each interface method
• 100 for each class
• 20 for each class method
• 10 for each class constructor
• 20 for each class variable

You can use the raw data given in the output file to calculate your own required documentation level if you wish. Javaanal estimates the number of actual words of documentation by taking the number of times common words are found ('commonwords' variable above), and multiplying by seven. Note that JavaDoc actually puts each source code comment into the HTML files twice; this is taken into account in Javaanal's calculations.

Interpretation

Interpreting this kind of broad measure requires considerable expertise, and it is usually necessary to have the actual content of the documentation sampled by a documentation expert. After all, Javaanal can't tell whether your documentation actually makes sense!

However, broadly if your percentage of ideal documentation is low, it will mean that:

• development speed will be slowed
• the code will be hard (perhaps impossible) to maintain
• maintenance will take longer
• you will be dependent on the knowledge in the heads of the original developers

If you have any concerns about interpretation, please get in touch with us and we'll help you out.

Disclaimer

HCi makes no representation whatsoever about the effectiveness, usefulness, utility or safety of this product. It is provided free of charge, and HCi would like to warn potential users that this product may provide misleading, dangerous, and just plain silly results if not used by our staff experts. Download and use entirely at your own risk.

Download it!

Click here to download (about 1.5M) version 1.3 of the utility. To install, unzip it and then run setup.exe.