Getting Started with Checkstyle
Checkstyle is an open source tool that enforces coding conventions and best practice rules for Java code. It works by analyzing Java source code and reporting any breach of standards. It can be integrated into your favorite IDE via a plug-in, so that developers can immediately see and correct any breaches of the official standards. It can also be used to generate project-wide reports that summarize the breaches found.
Checkstyle comes out-of-the-box with the standard Sun conventions, including more than 120 rules and standards, dealing with issues that range from code formatting and naming conventions to EJB best practices and code complexity metrics. Checkstyle supports standards related to:
Using Checkstyle from within Eclipse
- Javadoc comments
- Naming conventions
- File headers
- Import statements
- White space
- Coding problems
- Class design
- And other miscellaneous issues
Checkstyle can be used in a variety of ways, including from the command line or from within an Ant or Maven build script. However, the most efficient way to use it is from within the IDE, as corrections can be made immediately and with little effort. Plug-ins exist for most of the major Java IDEs, including Eclipse, IntelliJ, NetBeans, JBuilder, and even JEdit. Next I'll look at how this is done using Eclipse.
The Eclipse Checkstyle Plug-in is found at http://eclipse-cs.sourceforge.net/index.html. The first thing you will need to do is to install the plug-in. The simplest way to do this is to use the plug-in's Remote Update site (see Figure 1).
Figure 1. Installing Checkstyle on Eclipse: Installing the Checkstyle plug-in for Eclipse using the remote update site is simple.
Figure 2. Activating Checkstyle in an Eclipse Project: Checkstyle offers a plug-in for the Eclipse IDE as well as many others.
Once the plug-in is installed, you can activate Checkstyle checks for your particular project (see Figure 2). Open the project properties window (Project->Properties), select the Checkstyle properties entry, make sure the 'Checkstyle active for this project' check box is ticked, and press OK. At this point, Checkstyle runs as a background task and audits the source code in your project. This may take some time, depending on the size of your project.
When Checkstyle finishes its audit, you will probably have a long list of standards violations, listed as warnings in the Problems view pane. Clicking on a problem in this list will automatically jump to the offending code segment.
The Checkstyle plug-in works in the same way as the Java compiler. Now, whenever you edit and save your Java classes in a Checkstyle-activated project, your code is automatically checked and any infringements are highlighted and explained (see Figure 3). They are rather hard to miss: the offending code is highlighted in yellow, with a corresponding marker in the margin for good measure.
In any project where coding standards are to be enforced, developers need to work with an IDE correctly configured with Checkstyle. If properly encouraged, they will come to consider coding standard errors almost in the same way as syntax errors, correcting their code as they write it. And the project standards will be gradually and smoothly adopted by all team members. This is by far the most efficient way of enforcing coding standards.
On the other hand, running Checkstyle on a large existing code base can be positively demoralizing, especially if no (or different) coding standards were previously enforced, as the number of errors can be overwhelming. This is an important factor when considering how to introduce coding standards into an organization.
In the next section, I'll look at how you can customize Checkstyle coding standards to your team's particular requirements.
Figure 3. Checkstyle in Action: The Checkstyle Eclipse plug-in will remind many of a compiler; it steps through the code and highlights issues in yellow.
Figure 4. Configuration: Here I'm creating a new configuration file that Checkstyle will add to its reference data.
Customizing Coding Standards from within Eclipse
The Sun coding standardsprovided "out-of-the-box" via a configuration filecan be overwhelming at times. Checkstyle may well come up with hundreds of relatively minor rule violations (white spaces at the ends of lines, for example), especially if a lot of code has already been written without Checkstyle in place. The more important standards may get lost in the mass of minor and relatively unimportant ones. This can result in two possible negative side-effects:
- Developers will become discouraged, and ignore all rule violations, which tends to defeat the purpose of installing Checkstyle in the first place.
- Developers will become overly zealous, and pass hours removing spaces from the ends of lines, and so forth. This will produce nice clean code, but will probably slow down developer productivity considerably.
To optimize the adoption of coding standards and the use of Checkstyle to enforce them, a more flexible approach is often needed. The easiest way to do this is to create a custom set of coding standards that is specifically designed either for your company or for a single project.
You can do this fairly easily from within Eclipse (see Figure 4). Go into the Preferences window, and select the Checkstyle preferences. You will see some built-in configuration files (the Sun coding standards and a slightly modified version of the Sun standards adapted to the default code formatting used by Eclipse).
To create a new Checkstyle configuration file, just click "New." Several types of configuration files are available, including:
- Built-in Configurations, for example, the Sun coding standards, which are delivered with the Checkstyle plug-in, and which cannot be altered.
- Internal Configurations, which are stored within the Eclipse metadata. These are useful for experimenting locally with new configurations, but cannot (easily) be shared with other team members.
- External Configurations, which are imported from an external source. External configurations may be imported from an external file on a local disk ("External Configuration"), or from a web server ("Remote Configuration"), or be stored within the Eclipse project, under configuration management, for example ("Project Relative Configuration").
Project Relative Configurations are particularly useful when the corresponding Checkstyle configuration file is also used in the build process by other tools such as Ant or Maven.
When you build a new set of coding standards, the simplest option is to start with an Internal Configuration, and then to export and publish it once you (and the rest of the team) are happy with it.
|Figure 5. Customization: You can enforce custom styles and rules by creating your own Checkstyle configuration file.|
Configuring the Checkstyle configuration file using the plug-in is straightforward. When you click on the new configuration, you open a window displaying the available Checkstyle modules, along with those that have been activated for this configuration file (see Figure 5). To add a module to your configuration file, simply click on the module and configure it to your particular needs. Each module has its own specific configuration parameters.
It is important to get buy-in from your development team for any coding standards initiative. A good approach is to go through the list of standards with your team, discussing each one, and then to configure your module according to your project needs and standards. This helps developers understand the impetus behind each rule, which will encourage adoption.