AnnotationUseStyle

Since Checkstyle 5.0

Description

Checks the style of elements in annotations.

Annotations have three element styles starting with the least verbose.

ElementStyleOption.COMPACT_NO_ARRAY
ElementStyleOption.COMPACT
ElementStyleOption.EXPANDED

To not enforce an element style a ElementStyleOption.IGNORE type is provided. The desired style can be set through the elementStyle property.

Using the ElementStyleOption.EXPANDED style is more verbose. The expanded version is sometimes referred to as "named parameters" in other languages.

Using the ElementStyleOption.COMPACT style is less verbose. This style can only be used when there is an element called 'value' which is either the sole element or all other elements have default values.

Using the ElementStyleOption.COMPACT_NO_ARRAY style is less verbose. It is similar to the ElementStyleOption.COMPACT style but single value arrays are flagged. With annotations a single value array does not need to be placed in an array initializer.

The ending parenthesis are optional when using annotations with no elements. To always require ending parenthesis use the ClosingParensOption.ALWAYS type. To never have ending parenthesis use the ClosingParensOption.NEVER type. To not enforce a closing parenthesis preference a ClosingParensOption.IGNORE type is provided. Set this through the closingParens property.

Annotations also allow you to specify arrays of elements in a standard format. As with normal arrays, a trailing comma is optional. To always require a trailing comma use the TrailingArrayCommaOption.ALWAYS type. To never have a trailing comma use the TrailingArrayCommaOption.NEVER type. To not enforce a trailing array comma preference a TrailingArrayCommaOption.IGNORE type is provided. Set this through the trailingArrayComma property.

By default, the ElementStyleOption is set to COMPACT_NO_ARRAY, the TrailingArrayCommaOption is set to NEVER, and the ClosingParensOption is set to NEVER.

According to the JLS, it is legal to include a trailing comma in arrays used in annotations but Sun's Java 5 & 6 compilers will not compile with this syntax. This may in be a bug in Sun's compilers since eclipse 3.4's built-in compiler does allow this syntax as defined in the JLS. Note: this was tested with compilers included with JDK versions 1.5.0.17 and 1.6.0.11 and the compiler included with eclipse 3.4.1.

See Java Language specification, §9.7.

Properties

name	description	type	default value	since
closingParens	Define the policy for ending parenthesis.	ClosingParensOption	`never`	5.0
elementStyle	Define the annotation element styles.	ElementStyleOption	`compact_no_array`	5.0
trailingArrayComma	Define the policy for trailing comma in arrays.	TrailingArrayCommaOption	`never`	5.0

Examples

To configure the check:


<module name="Checker">
  <module name="TreeWalker">
    <module name="AnnotationUseStyle"/>
  </module>
</module>

Example:


@SuppressWarnings("unchecked") // ok as it's in implied style
@Deprecated // ok as it matches closingParens default property
@SomeArrays({"unchecked","unused"}) // ok as it's in implied style
public class Example1
{

}

// violation below 'Annotation style must be 'COMPACT_NO_ARRAY''
@SuppressWarnings(value={"unchecked"})
@Deprecated() // violation 'Annotation cannot have closing parenthesis'
// violation below 'Annotation array values cannot contain trailing comma'
@SomeArrays(value={"unchecked","unused",})
class TestStyle1
{

}

To configure the check to enforce an expanded style, with a closing parenthesis and a trailing array comma set to never.


<module name="Checker">
  <module name="TreeWalker">
    <module name="AnnotationUseStyle">
      <property name="elementStyle" value="expanded"/>
      <property name="closingParens" value="never"/>
      <property name="trailingArrayComma" value="never"/>
    </module>
  </module>
</module>

Example:


@SuppressWarnings("unchecked") // violation 'Annotation style must be 'EXPANDED''
@Deprecated // ok as closingParens property set to never
// violation below 'Annotation style must be 'EXPANDED''
@SomeArrays({"unchecked","unused"})
public class Example2
{

}

@SuppressWarnings(value={"unchecked"}) // ok as elementStyle set to expanded
@Deprecated() // violation 'Annotation cannot have closing parenthesis'
// violation below 'Annotation array values cannot contain trailing comma'
@SomeArrays(value={"unchecked","unused",})
class TestStyle2 {

}

To configure the check to enforce an expanded style, with a closing parenthesis and a trailing array comma set to never.


<module name="Checker">
  <module name="TreeWalker">
    <module name="AnnotationUseStyle">
      <property name="elementStyle" value="compact"/>
      <property name="closingParens" value="always"/>
      <property name="trailingArrayComma" value="ignore"/>
    </module>
  </module>
</module>

Example:


@SuppressWarnings("unchecked") // ok as element style set to compact
@Deprecated // violation 'Annotation must have closing parenthesis'
@SomeArrays({"unchecked","unused"}) // ok as it's in compact style
public class Example3
{

}

// violation below 'Annotation style must be 'COMPACT''
@SuppressWarnings(value={"unchecked"})
@Deprecated() // ok as closingParens set to always
// violation below 'Annotation style must be 'COMPACT''
@SomeArrays(value={"unchecked","unused",})
class TestStyle3 {

}

To configure the check to enforce a trailing array comma, with ignoring the elementStyle and a closing parenthesis.


<module name="Checker">
  <module name="TreeWalker">
    <module name="AnnotationUseStyle">
      <property name="elementStyle" value="ignore"/>
      <property name="closingParens" value="ignore"/>
      <property name="trailingArrayComma" value="always"/>
    </module>
  </module>
</module>

Example:


@SuppressWarnings("unchecked") // ok as element style set to 'ignore'
@Deprecated // ok as 'closingParens' is set to 'ignore
// violation below 'Annotation array values must contain trailing comma'
@SomeArrays({"unchecked","unused"})
public class Example4
{

}

// violation below 'Annotation array values must contain trailing comma'
@SuppressWarnings(value={"unchecked"})
@Deprecated() // ok as 'closingParens' is set to 'ignore
// ok below as it has a trailing array comma
@SomeArrays(value={"unchecked","unused",})
class TestStyle4 {

}

Example of Usage

Checkstyle Style

Violation Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.annotation

Parent Module

TreeWalker