Skip to content

[doc] Rework rule guidelines #2510

@adangel

Description

@adangel

Part of #1139

Current content: https://pmd.github.io/latest/pmd_userdocs_extending_rule_guidelines.html

Rewrite or dispatch the Rule guidelines. Details about PMD's formatting settings and
build process are irrelevant and belong to the devdocs section. This section's intended
audience is developers than want to write rules for themselves. Pushing their rules back
to PMD should be suggested, but the relevant doc should be linked and not duplicated
here (it's also out of date).

Mention quality aspects like having tests (both positive and negative cases). That will
help when refactoring/changing anything and is a prove that the rule works as intended.

What should be in the message of a rule? What should be in the description? E.g.
Description should start with a summary as a first sentence (like javadoc). And then
provide further explanations (why is this best practice, what would/could happen if...,
possible consequences / impacts / conflicts with other rules, ...).
While we might not provide this information for each built-in rule out of the box,
it would be good to have a guideline to refer to as in "that's what we would like to have".

Remove Jaxen reference here.

See also https://pmd.github.io/latest/pmd_devdocs_major_rule_guidelines.html

Metadata

Metadata

Assignees

No one assigned

    Labels

    an:enhancementAn improvement on existing features / rulesin:documentationAffects the documentation [doc]

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions