Java Check Style Tool

Author: Oliver Burn

Introduction

Checkstyle is a development tool to help programmers write Java code that adheres to a coding standard. Its purpose is to automate the process of checking Java code, and to spare humans of this boring (but important) task.

My experience from using a similar proprietary tool at a previous employer was that it increased the productivity of code reviews. This is because it allowed the reviewers to get on with reviewing the code and not get into "style" debates. It also helped that all the code had the same style.

The things that checkstyle checks for are:

The following list outlines some things checkstyle is not:

Getting checkstyle

Binary and source distributions are from http://www.puppycrawl.com/checkstyle.

system requirements

To run checkstyle you will need:

To build checkstyle you will need:

Installing and Running Checkstyle

The following ways are supported for running checkstyle:

I have tested checkstyle using JRE1.2.2 and JRE1.3 on Windows 2000.

What checkstyle checks

Long Lines

Checks for lines that are longer that a specified length. The default is "80".

Tab characters

Checks for lines that contain tab ('\t') characters. This can be turned off.

Format of variable names

Verifies that the format of the variable names conform to a specified regular expression. The formats can be overridden. The following table outlines the defaults:

Scope Default Format Example
static and final ^[A-Z]([A-Z0-9_]*[A-Z0-9])?$
The exception to the rule is for serialVersionUID.
public static final int MAX_ROWS = 2;
static only ^s[A-Z][a-zA-Z0-9]*$ private static int sNumCreated = 0;
non static ^m[A-Z][a-zA-Z0-9]*$ private int mNumCreated = 0;

Format of parameter names

Verifies that the format of parameter names conform to a specified regular expression. The default is ^a[A-Z][a-zA-Z0-9]*$.

Format of type names

Verifies that the format of class and interface names conform to a specified regular expression. The default is ^[A-Z][a-zA-Z0-9]*$.

Access Permissions

Checks for data members that are not declared private. Also finds static non-final data members that are not declared as private.

Note: you can turn on allowing protected data members.

White space

Checks for the following use of white space:

Missing Braces

Checks for missing braces {}'s for the following constructs:

Javadoc tags

Checks that the following constructs have a Javadoc comment:

Javadoc comments for class and interface declarations are checked to ensure that the @author tag exists. This can be turned off.

Javadoc comments for methods are checked to ensure that the following tags exist (if required):

For example the following is valid:

    /**
     * Checks for a return tag.
     * @return the index of the next unchecked tag
     * @param aTagIndex the index to start in the tags
     * @param aTags the tags to check
     * @param aLineNo the line number of the expected tag
     **/
    public int checkReturnTag(final int aTagIndex,
                              JavadocTag[] aTags,
                              int aLineNo)

Tip

It can be extremely painful writing or duplicating Javadoc for a method required for an interface. Hence checkstyle supports using the convention of using a single @see tag instead of all the other tags. For example, if the previous method was implementing a method required by the com.puppycrawl.tools.checkstyle.Verifier interface, then the Javadoc could be done as:

    /** @see com.puppycrawl.tools.checkstyle.Verifier **/
    public int checkReturnTag(final int aTagIndex,
                              JavadocTag[] aTags,
                              int aLineNo)

File Header

Ensure that the file starts with a specified header. The header contents are specified in a file. If no file is specified, checkstyle does not check for a header.

Tip

Most copyright headers will contain date information (for example the year) which will change over time. To support this, checkstyle supports specifying a line in the header to ignore when comparing the start of the file with the header. For example, consider the following header:

line 1: ///////////////////////////////////////////////////////////////////////
line 2: // checkstyle: Checks Java source code for adherence to a set of rules.
line 3: // Copyright (C) 2001  Oliver Burn
line 4: ///////////////////////////////////////////////////////////////////////

Since the year information will change over time, you can tell checkstyle to ignore line 3.

License

checkstyle: Checks Java source code for adherence to a set of rules.
Copyright (C) 2001  Oliver Burn

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

Feedback

If you have any feedback on this tool, please email me at checkstyle@puppycrawl.com. I am interested in any improvements you would like to see (or hopefully made!).

Also, send me email if you would like to be notified when a newer version of checkstyle is released.


Copyright © 2001 Oliver Burn. All rights Reserved.
$Id: index.html,v 1.6 2001/02/16 03:22:20 oburn Exp $