AnnotationLocation

Since Checkstyle 6.0

Description

Checks location of annotation on language elements. By default, Check enforce to locate annotations before target element, annotation should be located on separate line from target element. This check also verifies that the annotations are on the same indenting level as the annotated element if they are not on the same line.

Attention: Elements that cannot have JavaDoc comments like local variables are not in the scope of this check even though a token type like VARIABLE_DEF would match them.

Attention: Annotations among modifiers are ignored (looks like false-negative) as there might be a problem with annotations for return types:


public @Nullable Long getStartTimeOrNull() { ... }

Such annotations are better to keep close to type. Due to limitations, Checkstyle can not examine the target of an annotation.

Example:


@Override
@Nullable
public String getNameIfPresent() { ... }

Notes

This check does not enforce annotations to be placed immediately after the documentation block. If that behavior is desired, consider also using InvalidJavadocPosition.

Properties

name	description	type	default value	since
allowSamelineMultipleAnnotations	Allow annotation(s) to be located on the same line as target element.	boolean	`false`	6.0
allowSamelineParameterizedAnnotation	Allow one and only parameterized annotation to be located on the same line as target element.	boolean	`false`	6.4
allowSamelineSingleParameterlessAnnotation	Allow single parameterless annotation to be located on the same line as target element.	boolean	`true`	6.1
tokens	tokens to check	subset of tokens CLASS_DEF , INTERFACE_DEF , PACKAGE_DEF , ENUM_CONSTANT_DEF , ENUM_DEF , METHOD_DEF , CTOR_DEF , VARIABLE_DEF , ANNOTATION_DEF , ANNOTATION_FIELD_DEF , RECORD_DEF , COMPACT_CTOR_DEF .	CLASS_DEF , INTERFACE_DEF , PACKAGE_DEF , ENUM_CONSTANT_DEF , ENUM_DEF , METHOD_DEF , CTOR_DEF , VARIABLE_DEF , RECORD_DEF , COMPACT_CTOR_DEF .	6.0

Examples

To configure the default check to allow one single parameterless annotation on the same line:


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

Example:


class Example1 {
  @Nonnull
  private boolean field1; // ok
  @Override public int hashCode() { return 1; } // ok
  @Nonnull // ok
  private boolean field2;
  @Override // ok
  public boolean equals(Object obj) { return true; }
  @Mock DataLoader loader1; // ok
  @SuppressWarnings("deprecation") DataLoader loader2;
  // violation above, 'Annotation 'SuppressWarnings' should be alone on line'
  @SuppressWarnings("deprecation") public int foo() { return 1; }
  // violation above, 'Annotation 'SuppressWarnings' should be alone on line'
  @Nonnull @Mock DataLoader loader3;
  // violation above, 'Annotation 'Mock' should be alone on line'
}

Use the following configuration to allow multiple annotations on the same line:


<module name="Checker">
  <module name="TreeWalker">
    <module name="AnnotationLocation">
      <property name="allowSamelineSingleParameterlessAnnotation"
                value="false"/>
      <property name="allowSamelineParameterizedAnnotation" value="false"/>
      <property name="allowSamelineMultipleAnnotations" value="true"/>
    </module>
  </module>
</module>

Example:


class Example2 {
  @Nonnull
  private boolean field1;
  @Override public int hashCode() { return 1; } // ok
  @Nonnull
  private boolean field2;
  @Override
  public boolean equals(Object obj) { return true; }
  @Mock
  DataLoader loader1;
  @SuppressWarnings("deprecation") DataLoader loader;
  @SuppressWarnings("deprecation") public int foo() { return 1; } // ok
  @Nonnull @Mock DataLoader loader2;
  // ok above as 'allowSamelineMultipleAnnotations' set to true
}

Use the following configuration to allow only one and only parameterized annotation on the same line:


<module name="Checker">
  <module name="TreeWalker">
    <module name="AnnotationLocation">
      <property name="allowSamelineMultipleAnnotations" value="false"/>
      <property name="allowSamelineSingleParameterlessAnnotation"
                value="false"/>
      <property name="allowSamelineParameterizedAnnotation" value="true"/>
    </module>
  </module>
</module>

Example:


class Example3 {
  // violation below, 'Annotation 'Nonnull' should be alone on line.'
  @Nonnull private boolean field1;
  // violation below, 'Annotation 'Override' should be alone on line.'
  @Override public int hashCode() { return 1; }
  @Nonnull
  private boolean field2;
  @Override
  public boolean equals(Object obj) { return true; }
  @Mock
  DataLoader loader;
  @SuppressWarnings("deprecation") DataLoader loader1;
  @SuppressWarnings("deprecation") public int foo() { return 1; }
  // violation below, 'Annotation 'Nonnull' should be alone on line.'
  @Nonnull @Mock DataLoader loader2;
  // violation above, 'Annotation 'Mock' should be alone on line.'
}

Use the following configuration to only validate annotations on methods to allow one single parameterless annotation on the same line:


<module name="Checker">
  <module name="TreeWalker">
    <module name="AnnotationLocation">
      <property name="tokens" value="METHOD_DEF"/>
      <property name="allowSamelineMultipleAnnotations" value="false"/>
      <property name="allowSamelineSingleParameterlessAnnotation"
                value="true"/>
      <property name="allowSamelineParameterizedAnnotation" value="false"/>
    </module>
  </module>
</module>

Example:


class Example4 {
  @NotNull private boolean field1; // ok, as 'tokens' property set to METHOD_DEF only
  @Override public int hashCode() { return 1; }
  @NotNull
  private boolean field2;
  @Override
  public boolean equals(Object obj) { return true; }
  @Mock
  DataLoader loader1;
  @SuppressWarnings("deprecation") DataLoader loader;
  @SuppressWarnings("deprecation") public int foo() { return 1; }
  // violation above, 'Annotation 'SuppressWarnings' should be alone on line.'
  @NotNull @Mock DataLoader loader2;
}

Example of Usage

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