Rough guide to Checkstyle (CS)

Why use CS?

This was my first question when one of my former colleagues decided that our project needed CS. His answer to me was something along the lines of, if everyone codes using CS then there will be more consistency and better code will be produced. Now at first I thought that that response was BS. But after using it for 3 months, I wouldn’t like to go back! It does make code more consistent (when combined with auto formatting) and in it provides many pointers on producing better code.

 

How to set up CS

Go to the Eclipse CS website and click on the “Download & Installation” button. Follow the instructions for adding in the CS plug-in to Eclipse. Once you’ve restarted Eclipse there will at first be no differences. CS by default is not enabled on a project as it will add many warnings when enabled.

Now, the best case is that you have a brand new project and no code, but chances are you have an established project and you’d like to see what CS looks like to decide whether to use it from now on. If you have the latter, you’re going to find that once you apply CS to your project, you’ll likely have hundreds (if not thousands) or warnings. Don’t be put off though. This is quite normal. We got round this by agreeing with every member of the team that if they edit a file, clean up the CS warnings and eventually you’ll find only a few hundred warnings left.

To enable CS, right click on your project, select properties and the properties box will pop up. Now, you might well notice two CS place holders, not sure why, but always use the top one. In the Main tab, tick “Checkstyle active for this project.” You have two options here, use the Sun default styles or create your own.

 
Use Sun Styles

Drop down “Simple – use the following check configuration for all files” and select the Sun style you’d like to see. Click ok, accept the rebuild of the project. You should notice that there are now lots of CS warnings.

 
Use Own Styles

Select the Local Check Configurations tab, click New, select you’re preferred type, I use Project Relative Configuration, give it a name, in location, type “/{name of project}/{src or other}/{name of file}” so in my case “/testproject/src/testcs.” You will probably get a pop up dialogue saying “The selected configuration file does not exist. Should an empty configuration file be created?”, press yes. Click ok. Select the Main tab again. Drop down “Simple – use the following check configuration for all files” and select the new file you just created. Agree to the project being rebuilt. You should now have a file in the src folder and if you open that file, you’ll notice its an XML file. You should also have realised that CS has not reported anything. That’s because we haven’t told it what we’re interested in.

Right click on the project again. Select properties. Select Checkstyle. Select the Local Check Configurations tab. Double click on your CS file. Now for every (and there are loads..) option on the left hand side, double click on the option, read it, see whether you’d like that style checked for and if so alter it if needed and then click ok, otherwise cancel. You should notice that in the “Configured modules for group “X”” you should see the ones you’ve chosen to be checked. E.g.

When done, click ok and click ok again on the properties window. Accept the rebuild of the project.

 

What does it look like when CS is applied?

Well that depends on whether you’ve chosen you’re own styles or selected the Sun styles. I would go for my own styles I have certain preferences that Sun thinks are wrong, like opening curly braces on a new line!

Here is what Sun CS styles look like on my very simple class:

As you can see, it’s complaining about a lot of things I wouldn’t agree with. So here is an image of my own style in use:

Please note that both images show custom check style warning colourings. Please see Configuring Eclipse Preferences

A lot better! The errors that are present are that the main method should be commented (fair) and that both int arrays should be declared final (fair). So I’d have to clean those up.

In case you’re interested, that CS rules file is available from here. It should have an MD5 sum of bc6869b2d2ab5143b5fc6c4cfd6d0edb.

 

How do I configure CS to work with auto formatting?

Click Window → Preferences, which will open the preferences window. Drop down Java → Code Style and select Clean Up. Create a new profile, E.g. mines called Victoria and this will pop up a new window where you can edit all the settings. Tick Format source code, Remove trailing whitespace, Correct indentation and Organise imports as a bare minimum. You can then go through all the tabs and apply anything else you’d like applied. When done click ok.

Next select Java → Code Syle → Formatter and again create a new profile and edit the settings when the window appears.

Next select Java → Editor → Save Actions and tick Perform the selected actions on save, tick Format source code and click apply.

In theory, all you need to do now is go to a java file, edit it very slightly, like insert a space and click save. The formatter will then kick in and remove half of the CS warnings as formatted code should adhere to the CS styles.

Configuring Eclipse Preferences

I find that by default the Eclipse colours are far too subtle to actually see properly. But once configured the workspace will be easier to navigate and problems and code will be clearer.

 

Changing Eclipse Preferences

Click Window → Preferences → The preferences panel will appear. Drop down General → Appearances and select Colors and Fonts. Drop down the Basic folder. Check that “Error text colour” is bright red. Now drop down the Java folder and select “Coloured labels – write access occurences.” Change the colour from the pale beige to something bright! I like bright green (RGB 0, 219, 0).

Click apply.

 

Still in Preferences panel, drop down General → Editors → Text Editors. Change the “Undo history size” from 200 to 500. Tick “Show print margin” and change the “Print margin column” from 80 to 200. Make sure “Show line numbers” is ticked! In “Appearance color options” select the “Find scope” option and change it from grey to something bright (I like bright yellow).

Click apply.

 

Still in Preferences panel, drop down General → Editors → Text Editors → Annotations. Select “Occurrences” and make sure the colour is something bright (I like bright green again). Select “Write Occurrences” and make sure the colour is something bright (I like bright orange). Select Errors and make sure the colour is something bright (I like the hot pink).

Click apply.

 

*If you have Checkstyle installed*

Select “Checkstyle warning (both if there are two) and make sure the colour is something bright (I like deep blue – that way you’ll be more inclined to fix the issues!)

Click apply.

 

Those are my basic checks and changes. If you have others, feel free to comment.

Click ok.

 

What does it look like?

In the following example above I have selected varargs and highlighted is where varargs is used (green) and where its first declared (orange). Also on the side bar to the right are the lines that the selected text is found. They now stand out enough from the side bar that you can see them and select them. We can also clearly see the error on the last line of the bottom for look. Again that is highlighted in the side bar and can be clicked on.

*For the Checkstyle warning colours see the article on Checkstyle*

m2eclipse plugin error message

I’ve been installing Eclipse with all of the plugins I usually use nowadays (m2eclipse, checkstyle, etc.) but had encountered a problem after installing m2eclipse. The error was as follows:

Could not calculate build plan: Missing:
----------
1) org.apache.maven.plugins:maven-resources-plugin:maven-plugin:2.4.1
Try downloading the file manually from the project website.
Then, install it using the command: 
mvn install:install-file -DgroupId=org.apache.maven.plugins -DartifactId=maven-resources-plugin -Dversion=2.4.1 -Dpackaging=maven-plugin -Dfile=/path/to/file
Alternatively, if you host your own repository you can deploy the file there: 
mvn deploy:deploy-file -DgroupId=org.apache.maven.plugins -DartifactId=maven-resources-plugin -Dversion=2.4.1 -Dpackaging=maven-plugin -Dfile=/path/to/file -Durl=[url] -DrepositoryId=[id]
----------
1 required artifact is missing.
for artifact: 
org.apache.maven.plugins:maven-resources-plugin:maven-plugin:2.4.1
from the specified remote repositories:
central (http://repo1.maven.org/maven2, releases=true, snapshots=false)

Rather non-descript error there. Had a quick google around and there are a few people posting similar error messages but none of the pages had an answer on how to fix it. I checked the .m2eclipse file to make sure it was correct, which it seems to be. And then I had a bit of a brain wave! (Unusual yes). Every post I’d seen had mentioned that the plugin was definitely in the repository, but Eclipse was claiming it couldn’t find it. So I checked ZoneAlarm and deleted all entries that didn’t have Access-trusted and internet. Lo and behold, Java™ Platform SE binary pops up a dialog box straight away and when I allowed it access, Eclipse began to download successfully from the repository!

But the error is still there… So attempt 2, add the plugin to the plugins tab, but move the plugin to the next version 2.4.2.

<plugins>
  	<plugin>
 		<groupId>org.apache.maven.plugins</groupId>
		<artifactId>maven-resources-plugin</artifactId>
		<version>2.4.2</version>
	</plugin>
</plugins>

The error is now gone, but not sure this is the best solution, so if anyone can think of a better one, let me know!

Anyway hope this helps someone else with this error message.