Guides for SE student projects »

Using Checkstyle

Checkstyle is a static analysis tool that can check Java code against a set of style rules.

Given below are some instructions on how to use Checkstyle for some common project tasks.

Configuring Checkstyle

Checkstyle expects configuration files for checkstyle (e.g., files that specify which style rules to follow) to be in ./config/checkstyle/ by convention.

The two config files to add are:

  • config/checkstyle/checkstyle.xml: Contains the set of code style rules to follow.
  • config/checkstyle/suppressions.xml: Contains which rules to suppress under in which files.

Checkstyle configuration matching our Java coding standard can be found in the AddressBook Level 3 project.

To suppress a rule for a segment of code, you can add in the comment //CHECKSTYLE.OFF: RuleName at the start of the code segment and //CHECKSTYLE.ON: RuleName at the end of the segment.

Using Checkstyle with Gradle

Prerequisite: The two config files checkstyle.xml and suppressions.xml are present (see the Configuring Checkstyle section above for more details on these two files).

Here is an example of relevant lines that should be in the build.gradle file.

build.gradle
plugins {
    id 'checkstyle'
    // other plugins
}

checkstyle {
    toolVersion = '10.2'
}

Some relevant Gradle tasks added by the CheckStyle plugin.

  • checkstyleMain: checks if the main code complies with the style rules
  • checkstyleTest: checks if the test code complies with the style rules

For example, you can run gradlew checkstyleMain checkstyleTest to verify that all your code complies with the style rules.

Using Checkstyle-IDEA plugin

Prerequisite: The two config files checkstyle.xml and suppressions.xml are present (see the Configuring Checkstyle section above for more details on these two files).

Given below are the steps to install the Checkstyle-IDEA plugin so that Intellij can alert you about code style problems as you write code.

  1. Install the Checkstyle-IDEA plugin as follows:

    1. File > Settings (Windows/Linux), or IntelliJ IDEA > Preferences…​ (macOS)
    2. Select Plugins (on the left slide menu in the dialog that pops up)
    3. Select Marketplace (on to top center of the same dialog box)
    4. Find the plugin.
    5. Restart the IDE to complete the installation.

  2. Click File > Settings…​ > Tools > Checkstyle

  3. Set Scan Scope to Only Java sources (including tests), so that the plugin will run checkstyle for our test source codes as well

  4. Ensure that the Checkstyle version is set to the one used by the project.
    If your project uses Gradle, you can check the build.gradle file to find the correct version.
    checkstyle idea scan scope

  5. Click the + sign under Configuration File

  6. Enter an arbitrary description e.g. addressbook

  7. Select Use a local Checkstyle file

  8. Use the checkstyle configuration file found at config/checkstyle/checkstyle.xml

  9. Click Next > Finish

  10. Mark Active for the newly imported check configuration
    checkstyle idea configuration

  11. Click OK

  12. To verify the plugin is set up correctly, temporarily modify the code to violate a style rule (e.g., add an extra line break before an {) and run the Checkstyle check using the plugin.

Troubleshooting

Problem: When importing checkstyle.xml, Checkstyle-IDEA plugin complains that The Checkstyle rules file could not be parsed. …​ The file has been blacklisted for 60s.

  • Reason: checkstyle.xml is written for a particular version, but the plugin was not configured to the correct version.
  • Solution: Ensure that you have selected the correct Checkstyle version that matches the version in build.gradle and have clicked Apply, as checkstyle.xml is written for Gradle’s checkstyle.

Problem: After setting up checkstyle.xml, Checkstyle-IDEA plugin does not seem to highlight the errors / real-time scanning seems broken.

  • Reason: The plugin may not immediately run after setting it up.
  • Solution: Restart the IDE.

Resources