Static code checking rules for responsible Java and Kotlin programming built on PMD, sponsored by Rabobank.
Rules are on performance, sustainability, multi-threading, data mix-up, and more.
The purpose of this project is to create, manage and share these rules, to code better software together: better software which is faster, uses less resources, has a smaller ecological footprint, is more stable, more confidential, with less effort and lower cost. More general, to promote responsibility by considering the concerns of the user, the environment, the engineer, the community and the company.
We have distilled these code checks from what we learned in several years of analyzing performance problems and failures found in code, tests and production situations. And the ruleset is growing every month.
We didn't find these checks in other places, like the standard PMD, FindBugs/Spotbugs, Checkstyle or Sonar rules. We are working with the PMD-team to move some of the jpinpoint rules in the standard rule set, as well as make PMD suitable for Kotlin.
Run the jPinpoint rules from the command-line using the PMD tool, from your favorite development environment with a PMD-plugin, or in SonarQube with the sonar-pmd-jpinpoint plugin next to the Sonar pmd plugin.
Documentation of the rules are here:
PMD-jPinpoint-rules is licensed under the Apache License, Version 2.0.
- How Bol uses the jPinpoint rules: How to prevent common performance defects with the jPinpoint PMD rules
- Jeroen Borgers presented at J-Fall Virtual 2020: Fixing your performance and concurrency bugs before they bite you
- Jeroen Borgers presented at Amsterdam JUG about the why, what and how of these code checking rules: Performance problem prevention | slides
To use the ruleset you can install:
- the PMD command line tool from PMD project at github and/or
- the PMDPlugin in you development environment.
After installing the tool you can run pmd.sh
or pmd.bat
similar to the following
pmd.sh \
-R PMD-jPinpoint-rules/rulesets/java/jpinpoint-rules.xml \
-d $your-project-src \
-f text
-
You need version from 2023-1 to 2024-1 of IntelliJ. Unfortunately the proper plugin version is not supported in 2024-2+ yet.
-
PMD Plugin: you need version 1.9.2 (until we migrated fully to PMD7). Install:
Settings > Plugins > Browse Repositories > Search 'PMD' > Select 'PMD' > Plugin homepage > Plugin Versions > 1.9.2 Download > config wheel > Install Plugin from Disk > choose downloaded zip file > OK > Restart IDE
-
Next, add the ruleset from this repo by URL to always be up-to-date:
Settings > Other Settings > PMD > RuleSets > + > Choose RuleSet > drop down > Choose 'jpinpoint-rules'
-
Alternatively, download and add your local copy: rulesets/java/jpinpoint-rules.xml
-
Options tab: check 'Skip Test Sources' and set your Java version
-
You can now perform the code checks using [right-click] on a folder or a file and choose:
Run PMD > Custom rules > jpinpoint-rules
-
If you want a short description on a violation: hover over a violation title to get a popup with a description.
-
Documentation on a violation is shown at the right side after clicking a violation. More details of the problem and solution are shown with right clicking 'Details'.
The Acanda PMD plugin seems to be the best one to use.
- Import it into eclipse.
- enable PMD through the properties of the project
- add the ruleset from this project rulesets/java/jpinpoint-rules.xml
In SonarQube, you need to install sonar-pmd plugin from the market place, and sonar-pmd-custom plugin for these custom rules.
To start development on the ruleset the PDM tool designer may come in handy. Download it from the PMD project at github and install it using the instructions on their site.
After installation and configuration you can start the designer from the command prompt:
designer.bat
or
./run.sh designer
The project can be build using maven. The build will perform the unit tests which will unit-test the rules. The next paragraph "Adding new rules" will describe in more detail where you can find the rule files. To run the unit tests run the following command from the project home directory of:
mvn clean test
or simply:
./test
You can add new rules using the steps below.
The steps basically tell you to create an issue, add documentation and create 3 files. As an example you can copy existing files and change the content according to your needs. Always work along the lines of what already exists.
For Kotlin: use the paths that contain /kotlin/
instead of /java/
.
- create an issue like 'Rule Request: AvoidRecreatingExpensiveThing' with simple compiling examples which can be used as tests. Use this issue reference with check-in.
- document the pitfall in the proper page and category in docs/ and regenerate the ToC
- add the Test class in
src/test/java/com/.../perf/lang/java/ruleset/yourruleset/YourRule.java
elements from the package structure are used to lookup the rules xml file you add next. The relevant items based on the example given are: lang/java/ruleset/yourruleset - rules go into xml files found in
src/main/resources/category/
in this case src/main/resources/category/java/yourruleset.xml. Also add a rule with nameYourRule
since that is what the framework expects. For new rule files (a new category) you will also need to register it in thecategories.properties
file found in the same directory (category/java/categories.properties) in this case addcategory/java/yourruleset.xml
- add the unit test in an xml file in
src/test/resources/com/.../perf/lang/java/ruleset/yourruleset/xml/YourRule.xml
. Pay attention to the package structure which is also dictated by the first java test class!
Depending on what you want to add you may also find it is sufficient to change one or more of the existing files. Or to add only a Test class and unit test xml file (steps 1 and 3).
Following are some conventions and recommendations on how to construct the unit test files:
- separate test code (create separate
<test-code>
blocks) - specify test code description (
<test-code><description>
) Start the description with:- violation: or
- no violation:
- specify number of occurrences (
<test-code><expected-problems>
) - specify line-numbers (
<test-code><expected-linenumbers>
) - code (
<test-code><code>
) conventions:- use class names like
Foo
- use method names like
bad
andgood
- add comment at the end of bad lines
//bad
- remove useless code and
import
statements
- use class names like
When running unit tests for Kotlin PMD 7 is needed. Make sure you have access to the PMD jars of the 7.0.0-SNAPSHOT
branch (e.g. mvn install the PMD 7.0.x jars from https://github.com/pmd/pmd). Use the Maven kotlin-pmd7
profile
when running the Kotlin unit tests.
- Indentation: Use spaces a.k.a. Disable Tabs: Settings>Editor>Code Style>Java>Use tab character [disable]
rulesets/java/jpinpoint-rules.xml
contains the pmd custom rule definitionssrc/main/java/pinpointrules
contains the Java code containing pitfalls for testing the rules.rulesets-merger
contains the Java code for a ruleset merger tool.
rulesets-merger/src
contains RulesetMerger.java for merging jpinpoint-rules.
The merger tool can be built with:
cd rulesets-merger
mvn clean install
Run the merger tool as follows:
cd rulesets-merger
mvn exec:java -Dexec.args="java"
or simply:
./merge
or for Kotlin instead of Java:
./merge kotlin
It will merge the rules from src/main/resources/category/java/*.xml
to create the jpinpoint-rules.xml file which can be used in your IDE.
Company specific rules are useful for instance for checking the right use of company specific or company-bought frameworks and libraries. Or for rules which are candidates for inclusion into jpinpoint rules, yet need to be validated first.
rulesets-merger/src
contains RulesetMerger.java for merging jpinpoint-rules with company specific rules. Copy rulesets-merger to your company specific rules directory and adjust a few constants at the top to make it work for your company.
The merge tool runs either for the java or the kotlin rules. Use the first argument to choose: java or kotlin.
After building, the merger tool can be run with:
cd rulesets-merger
mvn exec:java -Dexec.args="java"
or simply
./merge
or for Kotlin instead of Java:
./merge kotlin
This will attempt to lookup the PMD-jPinpoint-rules project (next to your own project)
and merge rulesets/[java|kotlin]/jpinpoint-rules.xml
together with your rule files (from src/main/resources/category/[java|kotlin]/*.xml
)
The resulting file can be used in your IDE.
It assumes you have the following repositories in directories next to each other:
PMD-Company-jPinpoint-rules
PMD-jPinpoint-rules (optional)
It can be built and run the same way.
It will generate two files:
company-rules.xml
company-jpinpoint-rules.xml
These files can be used in your IDE. The former only contains the company specific rules. The latter contains all rules combined and will only be generated if the optional PMD-jPinpoint-rules repo is available.
You can also do it yourself and specify the external repo to merge with explicitly:
cd target
java -jar java rulesets-merger-1.0-SNAPSHOT.jar PMD-jPinpoint-rules rulesets/java jpinpoint-rules.xml
or for Kotlin:
cd target
java -jar kotlin rulesets-merger-1.0-SNAPSHOT.jar PMD-jPinpoint-rules rulesets/kotlin jpinpoint-rules.xml
- Confluence export as HTML
- Converting HTML to Markdown
- Markdown TOC generator