Pmd: [java] DataClass example from documentation results in false negative.

[gustavopcassol]

Affects PMD Version: 6.27.0

Rule: DataClass

https://pmd.github.io/latest/pmd_rules_java_design.html#dataclass

Description: Using the code in "Example(s):" section of the documentation should return a violation case in the output, but it doesn't.

Code Sample demonstrating the issue:

Input:

public class DataClass {

  public int bar = 0;
  public int na = 0;
  private int bee = 0;

  public void setBee(int n) {
    bee = n;
  }
}

Output:

{"formatVersion":0,"pmdVersion":"6.27.0","timestamp":"","files":[],"suppressedViolations":[],"processingErrors":[],"configurationErrors":[]}

Expected outcome:

• PMD should have reported the code as a violation. It is a false negative.

Running PMD through: [Maven]

[Fernal73]

Shouldn't there be a regression tester that runs all these documented examples against the rules they're illustrative of?

[oowekyala]

If you add one public field the class is reported. The example should be corrected, probably a test case added.

Shouldn't there be a regression tester that runs all these documented examples against the rules they're illustrative of?

Examples are not runnable as tests, they're just illustrations. We already have a separate infrastructure to test rules. Parsing and running examples from a ruleset sounds like a bad idea to me. But it should be expected that some version of the examples is in the test file of the rule.

[Fernal73]

I'd expect it to be the other way round. You generate the documentation from the test examples you are currently testing against. It is an overhead to maintain two versions of the illustrative examples.

The point is to avoid duplication of effort. (DRY).

I'm not sure how this should be done, though.
One way would be to embed the test sources into the documentation via an include mechanism.
How would that work in the absence of a preprocessor? Would you need one?
Would you need a custom tool to do that? Would this make the documentation bloated given that examples are concise and illustrate both good and bad practices whereas test cases are individual pieces that are expected to pass or fail the rule?
Would this be overkill? On the other hand, documentation is visible and you wouldn't want what's presented to slip through the cracks.

Should markdown be considered for documentation?

https://stackoverflow.com/questions/4779582/markdown-and-including-multiple-files

You're probably already aware of this. But I'll put it in here, anyway.

https://dzone.com/articles/using-markdown-syntax-javadoc

Some documentation tools:

https://blog.education-ecosystem.com/code-documentation-tools/