Since Checkstyle 5.0
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.
name | description | type | default value | since |
---|---|---|---|---|
elementStyle | Define the annotation element styles. | ElementStyleOption |
compact_no_array
|
5.0 |
closingParens | Define the policy for ending parenthesis. | ClosingParensOption |
never
|
5.0 |
trailingArrayComma | Define the policy for trailing comma in arrays. | TrailingArrayCommaOption |
never
|
5.0 |
To configure the check:
<module name="AnnotationUseStyle"/>
Example:
@SuppressWarnings("unchecked") // OK @Deprecated // OK @SomeArrays({"unchecked","unused"}) // OK public class TestOne { } @SuppressWarnings(value={"unchecked"}) // Violation - parameter 'value' shouldn't be used @Deprecated() // Violation - cannot have a closing parenthesis @SomeArrays(value={"unchecked","unused",}) // Violation - cannot have a trailing array comma class TestTwo { }
To configure the check to enforce an expanded
style,
with a closing parenthesis and a trailing array comma set to never
.
<module name="AnnotationUseStyle"> <property name="elementStyle" value="expanded"/> <property name="closingParens" value="never"/> <property name="trailingArrayComma" value="never"/> </module>
Example:
@SuppressWarnings("unchecked") // Violation - parameters should be referenced @Deprecated // OK @SomeArrays({"unchecked","unused"}) // Violation - parameters should be referenced public class TestOne { } @SuppressWarnings(value={"unchecked"}) // OK @Deprecated() // Violation - cannot have a closing parenthesis @SomeArrays(value={"unchecked","unused",}) // Violation - cannot have a trailing array comma class TestTwo { }
To configure the check to enforce a compact
style,
with always including a closing parenthesis and ignoring a trailing array comma.
<module name="AnnotationUseStyle"> <property name="elementStyle" value="compact"/> <property name="closingParens" value="always"/> <property name="trailingArrayComma" value="ignore"/> </module>
Example:
@SuppressWarnings("unchecked") // OK @Deprecated // Violation - must have a closing parenthesis @SomeArrays({"unchecked","unused"}) // OK public class TestOne { } @SuppressWarnings(value={"unchecked"}) // Violation - parameter 'value' shouldn't be used @Deprecated() // OK @SomeArrays(value={"unchecked","unused",}) // Violation - parameter 'value' shouldn't be used class TestTwo { }
To configure the check to enforce a trailing array comma, with ignoring the elementStyle and a closing parenthesis.
<module name="AnnotationUseStyle"> <property name="elementStyle" value="ignore"/> <property name="closingParens" value="ignore"/> <property name="trailingArrayComma" value="always"/> </module>
Example:
@SuppressWarnings("unchecked") // OK @Deprecated // OK @SomeArrays({"unchecked","unused"}) // Violation - must have a trailing array comma public class TestOne { } @SuppressWarnings(value={"unchecked"}) // Violation - must have a trailing array comma @Deprecated() // OK @SomeArrays(value={"unchecked","unused",}) // OK class TestTwo { }
All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.
com.puppycrawl.tools.checkstyle.checks.annotation