checkstyle/checkstyle

Move violation comments out of Javadoc for all input files

Open

#19764 opened on Apr 29, 2026

View on GitHub
 (5 comments) (0 reactions) (0 assignees)Java (8,005 stars) (8,668 forks)batch import
approvedgood first issuemiscellaneous

Description

Follow-up of #19756

Background

Putting violation comments (i.e. // violation xxx) inside Javadoc is considered a bad practice as they visually mix with target code. For example,

Bad

/**
 * The following is a bad tag.
 * @mytag Hello   // violation 'Unknown tag 'mytag'.'
 * // violation below 'Unknown tag 'mytag'.'
 * @mytag
 */
public class InputJavadocTypeBadTag {}

Good

// violation 4 lines below 'Unknown tag 'mytag'.'
// violation 4 lines below 'Unknown tag 'mytag'.'
/**
 * The following is a bad tag.
 * @mytag Hello
 * @mytag
 */
public class InputJavadocTypeBadTag {}

Task

Ensure no violation comments inside Javadoc for all existing input files.

Here is a list of existing input files to be fixed: https://github.com/checkstyle/checkstyle/blob/b884b9a31b47be7b6e1a4d7d3b0f469a36e62637/config/checkstyle-input-suppressions.xml#L67-L71

How to contribute

  1. Choose a package from the list;
  2. Move all violation comments out of Javadoc;
  3. Remove all related suppressions;
  4. Update violation line numbers inside unit test methods, if any changed.
  5. Send PR.

Notes

  1. Moving violating comments around requires adding (X lines) above/below to make sure they still reference the same line. You can refer to guide to specify violations for syntax.
  2. Make sure no input files exceed the limit of 120 lines.

Example of expected update https://github.com/checkstyle/checkstyle/pull/19766

Contributor guide