Code Analyzer User's Guide

July 19, 2005


Table of Contents


1. Introduction

2. Definitions

3. Analysis Concepts

4. Creating a Code Set

5. Working With Comment Sets

6. Working With Extension Sets

7. Analyzing a Code Set

8. Analysis Results

9. Analysis Reports

10. Notes

1. Introduction

Code Analyzer is a tool for basic software source metrics. It can calculate these metrics across multiple source trees as one coherent "Code Set". It allows exclusion of portions of an included source tree by individual file or for all files below a given "sub-tree". It utilizes a set of defined file extensions (Extension Set) to filter the source tree. It calculates metrics by file extension type as well as cumulatively for all extension types. It can also generate simple text report files so that results can be archived.

The Code Analyzer GUI is built around the java tree display component, JTree. Projects (or Code Sets) are constructed by adding branches to the tree. Files or sub-branches are included or excluded through mouse popup menus as the user navigates the tree.

 

2. Definitions

Analyze - traverse the Code Set tree, parsing each file whose extension is valid as determined by the Code Set's selected Extension Set, and calculating metrics (or statistics) as the file is parsed.

Code Set - a collection of source files built by adding directory trees to the root node, which represents the current Code Set.

Code Line - a line of source containing code. The line may also contain comments, thus a line can be both a comment and code line simultaneously.

Comment - an object which defines a valid comment form by defining the opening string, if it is a comment which extends to the end of the line (EOL), and, if not an EOL comment, the closing string.

Comment Line - a line of source containing a comment. The line may also contain code, thus a line can be both a comment and code line simultaneously.

Comment Set - a collection of Comment objects which define the valid comment formats for a given file extension type.

Extension - an object which describes a file extension and its associated Comment Set.

Extension Set - a collection of Extension objects which define all the valid file extensions for a Code Set.

File Node - an object which describes a file or file folder's characteristics. These include file system details, inclusion status and metrics for the file or folder.

"Green" File or Folder Icons - a file or folder which has been analyzed and which includes valid metric information. This information can be viewed in the results pane (right side of the window), or by right-clicking while pointing at the file or folder.

"Red" File or Folder Icons - a file or folder which has been excluded from analysis and the resulting metrics.

Whitespace Line - a line of source containing no comments or code.

 

3. Analysis Concepts

Code Analyzer objects have the following hierarchical relationship:

 

4. Creating a Code Set

1) Select an Extension Set - the Extension Set is used not only during analysis, but also as a filter for the Code Set tree display. It is not imperative that it is selected before building a Code Set, but you will not be able to save the Code Set or analyze the Code Set until the Extension Set has been selected. To select an extension set, goto "Tools|Extension Sets|Select".

2) Add "Branches" to the Code Set - right click on the root node and select "Add Branch" from the menu. This will open a File Open dialog from which you can select a directory to add to the Code Set. All files (which "match" the selected Extension Set) and directories beneath this directory (folder) will be added to the Code Set.

3) Exclude Unwanted Files or Folders - to exclude a file or folder from the Code Set, right click the mouse while pointing at the file or folder. Select "Exclude" from the menu. The file or folder will become red in color to signify that it is excluded. If it is a folder, all files and folders beneath it will also be excluded.

4) Save the Code Set - once the Code Set and Extension Set have been defined or selected, the Code Set (with Extension Set selection) can be saved for later retrieval. Select "File|Save Code Set".

 

5. Working With Comment Sets

Comment sets are required for proper definition of file extensions. Each file extension object requires one and only one Comment Set.

To create a new Comment Set, select "Tools|Comment Sets|Add". A dialog will appear which allows you to name the new set, add comment definitions for it, and save it. There are several built-in Comment Sets that may be all you require. If not, you may define your own additional sets.

To edit an existing Comment Set, select "Tools|Comment Sets|Edit". Select the Comment Set you wish to edit from the resulting drop down menu. A dialog will appear which allows you to edit the Comment Set you selected. Note that you cannot edit any of the built-in Comment Sets.

To delete an existing Comment Set, select "Tools|Comment Sets|Delete". Select the Comment Set you wish to delete from the resulting drop down menu. Note that you cannot delete any of the built-in Comment Sets.

 

6. Working With Extension Sets

A valid Extension Set selection is required to perform analysis on a Code Set. Further, the selected Extension Set is used to filter the Code Set tree display.

To create a new Extension Set, select "Tools|Extension Sets|Add". A dialog will appear which allows you to name the new set, add extension definitions for it (including each Extension's corresponding Comment Set), and save it. There are several built-in Extension Sets that may be all you require. If not, you may define your own additional sets.

To edit an existing Extension Set, select "Tools|Extension Sets|Edit". Select the Extension Set you wish to edit from the resulting drop down menu. A dialog will appear which allows you to edit the Extension Set you selected. Note that you cannot edit any of the built-in Extension Sets.

To delete an existing Extension Set, select "Tools|Extension Sets|Delete". Select the Extension Set you wish to delete from the resulting drop down menu. Note that you cannot delete any of the built-in Extension Sets.

To select a new Extension Set for the current Code Set, select "Tools|Extension Sets|Select". Select the Extension Set from the resulting drop down menu.

 

7. Analyzing a Code Set

To analyze a Code Set, select "Run|Run". This process may take some time, based on the size of the Code Set. Progress is indicated in the progress bar near the bottom left side of the window. Progress is also indicated as the included files and folders will turn "green" in the Code Set tree view after they have been analyzed.

To stop analysis before it has completed, select "Run|Stop". The Code Set will have all metrics reset to empty or zero-value.

Note:

1) A line of source may be both a comment and a code line simultaneously. An example is:
myInt = 10;     // set myInt = 10

2) Therefore, the sum (code + comments + whitespace) may often be greater than the total lines metric.

3) During analysis, the Code Set tree view will be disabled. Mouse events are ignored until the analysis is complete.

4) During analysis, the majority of the menu selections such as "File|Load Code Set" or "Tools|Extension Sets|Select" will result in a warning only in the status display. This is for obvious reasons. Stopping the analysis, creating new Comment or Extension Sets, and Help functions will remain functional.

 

8. Analysis Results

Analysis results are available in three forms.

1) The results view will display metrics for the *selected* item in the Code Set tree view. For the root node and any folder there is one tab for each extension of the Extension Set plus one tab for the aggregate of all files. For files there is one tab labaled with the file name.

2) Right-clicking on any item in the Code Set tree view and selecting "Show Stats" will produce a dialog containing the aggregate metrics for that file, folder, or root node.

3) Report files - please see the following section.

Note:

Prior to analysis, all items will have empty, or zero-value, metrics.

 

9. Analysis Reports

Report selections are found under the "Reports" menu item. Selecting any of the report types will open a file open dialog so that you can choose the filename for the report. The full reports (last 3) will then open a second dialog to allow selection of folders only or files and folders for the report.

The following reports are available:

1) Selected File Summary - this is very similar in format to the on screen display for individual files in the results pane.

2) Code Set Summary - summary report for the entire Code Set and each branch within the Code Set.

3) Full Text Report - this report contains either all folders or all files and folders for the Code Set output in a tabular form with each file or folder occupying one row in the report.

4) Full CSV Report - this report contains either all folders or all files and folders for the Code Set output in a tabular form with each file or folder occupying one row in the report. Each value in a given row is delimited by commas (comma seperated values). This format can be easily imported into Excel or OpenOffice spreadsheets for historical comparisons, archiving, or custom charts and reports.

5) Full HTML Report - this report contains either all folders or all files and folders for the Code Set output in a tabular form with each file or folder occupying one row in the report. The report is generated as a fully compliant html page suitable for web site publishing.

Note:

Prior to analysis, generated reports will either be empty or only contain file header information.

 

10. Notes

1) This application started as a VC++ implementation produced in my spare time over a 2 week period because there was simply nothing out there that was light and not part of a big and expensive tool set (several come to mind). Necessity is truly the mother of invention. After 3 or 4 years of moving any non-windows-homed development trees to my windows PC just to generate metrics, I realized it was time to learn java. It was a good excuse to learn and a perfect use of the platform-independent nature of java. This application is the result. It was a true joy to develop in java using Netbeans.

2) Enhancement or design suggestions are welcome! This meets my current needs, but I have considered such things as complexity analysis and advanced, project-wide, multi-format file, source formatting. If you have other ideas, I'll be glad to consider/discuss them. I can be contacted via the project page on SourceForge in a number of ways.

3) The intended audience for Code Analyzer is software managers and software engineers. To that end, I want to add capabilities that are useful to such people (like me).