Cruft4J

  Overview
  How to Run
    Command Line
    Maven
  Benchmarks
  About
    Source Code
    Score
    License

Overview

Cruft4J is a static source code analysis tool which reports on the maintainability (or "cruftiness") of your Java code. Whereas other tools generate an unwieldy list of maintainability violations from which it's difficult to know what to do, Cruft4J generates one score which is based on just two things: cyclomatic complexity and copy-paste.

With this score, you can better understand how your code base measures up against other systems (see open source benchmarks) and also track over time whether things are getting better or worse.

Obviously this score isn't perfect, but that's not the point. The goal is to get the conversation started with managers and developers about code quality, and that's easier to do this with one number rather than with a list of obscure violations. Once the conversation is started, however, the team can discuss how to improve, using the excellent, more fine grain-tools like Sonar, PMD, and others, or implementing development best practices like code reviews, etc.

Running Cruft4J is easy: currently you can run it from the command line, or within Maven, and in the future I hope to support Ant, Gradle, Jenkins, and possibly Eclipse.

How to Run

Command Line

The easiest way to run Cruft4J is from the command line. First, make sure you have Java 1.5 or higher installed. Download Cruft4J from here, and unzip to some directory (e.g. C:\Cruft4J). This will be referred to here as your CRUFT4J_HOME.

Next, open a command prompt, and cd to your CRUFT4J_HOME directory. From here, type...

That's it! This will analyze all Java code within the specified source directory, and then generate a set of HTML reports in the CRUFT4J_HOME/output/ directory. If you want to store your output in a different directory, try...

Optionally, you may set your CRUFT4J_HOME as an environment variable, called (of course!) CRUFT4J_HOME. Also, put CRUFT4J_HOME on your path, and now you can run Cruft4J from any directory.

Maven

Through the magic of Maven, hooking Cruft4J into your build is quite easy. As of now, Cruft4J is not in the pulic repo, but I'm working on this. In the mean time, you can get the source from GitHub here, and just build both the cruft4j-calculator and cruft4j-maven projects to install to your local repo.

Once Cruft4J is in your repo, it's just a matter of configuring in your pom.xml. A full sample build file is here, but the important part is just configuring the Cruft4J plugin, like so:

There are a couple important things to note. First, given the configuration above, Cruft4J will run during the verify phase (according to Maven is the time to "run any checks to verify the package is valid and meets quality criteria"), but you're obviously free to change this. To test this out, in the directory of your pom.xml, run:

...and this will calculate a Cruft4J score, and generate a set of reports within the target/cruft4j directory.

Now, in terms of improving overall software quality, it's often helpful to draw the proverbial line in the sand, and say "we may not be ecstatic about the level of quality, but we commit to not letting it get any worse." To this end, a "cruft threshold" can be set, using the following configuration:

Given this configuration, if the code's cruft score ever goes above 40, then the build will fail. Pretty harsh, but perhaps necessary if code quality is important enough to you! To see what a reasonable Cruft Score is, check out the open source benchmarks, where you can see how popular open source projects score.

You can also set a threshold for the raw Cruft Score (i.e. before being scaled by lines of code) with this configuration:

Finally, if you want to take advantage of Cruft4J's trend reports to see how code quality has been tracking over time, then you'll want to specify the output directory where the reports and, more importantly, the Cruft4J database will be stored:

Benchmarks