[java] Fix #1102: improve consistency of utility class detection across rules by UncleOwen · Pull Request #6691 · pmd/pmd

UncleOwen · 2026-05-17T18:52:58Z

Describe the PR

This PR standardizes what UseUtilityClassRule and JavaRuleUtil.isUtilityClass() (used by ClassNamingConventionsRule) mean by the term "utility class."

The new common definition is:

A class is a utility class, if and only if it fulfills ALL of the following criteria:

ALL member functions, member variables, nested classes, and initializers are static.

The class has at least one member function, member variable, or nested class that is not private.

The class is neither abstract nor an interface.

The class has no superclasses and implements no interfaces. ~~(This might change in the future.)~~

The class has no main method.

Related issues

Fix [java] Improve consistency of utility class detection across rules #1102

Ready?

Added unit tests for fixed bug/feature
Passing all unit tests
Complete build ./mvnw clean verify passes (checked automatically by github actions)
Added (in-code) documentation (if needed)

pmd-actions-helper · 2026-05-17T19:18:45Z

Documentation Preview

Compared to main:
This changeset changes 8 violations,
introduces 42 new violations, 0 new errors and 0 new configuration errors,
removes 73 violations, 0 errors and 0 configuration errors.
There are 0 changed duplications, 0 new duplications and 0 removed duplications.
There are 0 changed CPD errors, 0 new CPD errors and 0 removed CPD errors.

Regression Tester Report

(comment created at 2026-05-25 12:55:58+00:00 for 8fdaa02)

Changes in JavaRuleUtil.isUtilityClass() * Add support for nested classes * Abstract classes aren't utility classes * Classes with main() method aren't utility classes This was broken before and handled inconsistently

Changes in UseUtilityClass * Add support for initializers * Classes with main() method aren't utility classes * Remove special cases for JUnit3/4 suites - they are handled correctly by the current code.

The implementations are identical.

zbynek · 2026-05-24T19:39:14Z

The most significant user-facing change here is that classes that contain a main method are no longer considered utility classes -- maybe worth mentioning in release notes.

Checking https://github.com/pmd/java-regression-tests/blob/main/src/main/java/net/sourceforge/pmd/java/regression/tests/java21/Jep441_PatternMatchingForSwitch.java#L7 🤔

UncleOwen · 2026-05-24T19:52:45Z

Good idea. And I just noticed that this doesn't have a release_notes entry, yet.

UncleOwen · 2026-05-24T20:03:47Z

Checking https://github.com/pmd/java-regression-tests/blob/main/src/main/java/net/sourceforge/pmd/java/regression/tests/java21/Jep441_PatternMatchingForSwitch.java#L7 🤔

That's no longer a utility class because of https://github.com/pmd/java-regression-tests/blob/main/src/main/java/net/sourceforge/pmd/java/regression/tests/java21/Jep441_PatternMatchingForSwitch.java#L74C1-L76C55 and https://github.com/pmd/java-regression-tests/blob/main/src/main/java/net/sourceforge/pmd/java/regression/tests/java21/Jep441_PatternMatchingForSwitch.java#L121C1-L122C51

UncleOwen · 2026-05-24T20:09:58Z

Hmm... but you're right. That is fishy... Does having a non-static nested class make the outer class stateful? It doesn't, right?

UncleOwen · 2026-05-24T20:12:49Z

On the other hand: If we add a private, /throwing/ constructor to Jep441_PatternMatchingForSwitch, would we still be able to use those nested classes?

zbynek · 2026-05-24T20:51:14Z

Nested interfaces, records and enums are always static, so the two lines you linked should not affect the utility status of the parent.

Nested classes that are not static should probably still make the parent non-utility class.
If the inner class is private, the static modifier could be suggested by a new rule similar to https://www.jetbrains.com/help/inspectopedia/InnerClassMayBeStatic.html#InnerClassMayBeStatic.topic

UncleOwen · 2026-05-24T21:16:16Z

Nested interfaces, records and enums are always static, so the two lines you linked should not affect the utility status of the parent.

TIL. Thanks, that's definitely a TODO.

Nested classes that are not static should probably still make the parent non-utility class.

I think I agree, if only for consistency's sake. Oh, and because of JUnit Jupiters @Nested classes.

If the inner class is private, the static modifier could be suggested by a new rule similar to https://www.jetbrains.com/help/inspectopedia/InnerClassMayBeStatic.html#InnerClassMayBeStatic.topic

Do you want to write an issue for that, or should I?

zbynek · 2026-05-24T22:02:45Z

Do you want to write an issue for that, or should I?

#6711

adangel

I see, ClassNamingConvention already uses JavaRuleUtil.isUtilityClass, so nothing to change there.

Don't forget to update the rule descriptions of both rules to add the new definition for utility classes there:

pmd/pmd-java/src/main/resources/category/java/design.xml

Lines 1498 to 1502 in 7db7a0a

    
           For classes that only have static members, consider making them utility classes. 
        
           Note that this doesn't apply to abstract classes, since their subclasses may 
        
           well include non-static methods.  Also, if you want this class to be a utility class, 
        
           remember to add a private constructor to prevent instantiation. 
        
           (Note, that this use was known before PMD 5.1.0 as UseSingleton).

pmd/pmd-java/src/main/resources/category/java/codestyle.xml

Lines 265 to 267 in 7db7a0a

    
           For this rule, a utility class is defined as: a concrete class that does not 
        
           inherit from a super class or implement any interface and only has static fields 
        
           or methods.

Out of scope for this change, but maybe something to consider in the future: I don't think the name of the rule "UseUtilityClass" is a good name... It's more like: "Hey, this class looks like a utility class, but it still can be instantiated although it doesn't have state. This doesn't make sense. Consider to add a private constructor ..." The rule is named better maybe "InstantiableUtilityClass"?

…rnal/JavaRuleUtil.java Co-authored-by: Andreas Dangel <andreas.dangel@adangel.org>

zbynek

As discussed, interfaces, records and enums should not be considered for utility class check, otherwise looks good.

Co-authored-by: Andreas Dangel <andreas.dangel@adangel.org>

Update javadoc of JavaRuleUtil.isUtilityClass()

UncleOwen · 2026-05-25T11:30:32Z

Updated rule descriptions. Nested interfaces, records and enums are static, those no longer prevent a class from being considered a utility class.

~~Could someone please have a look at this test case? Why do I get a parse error? javac (21) compiles this code without issue. Is this a bug in our parser?~~

Co-authored-by: Andreas Dangel <andreas.dangel@adangel.org>

adangel

Thanks, looks good!

UncleOwen · 2026-05-25T15:25:05Z

Thanks for the reviews!

zbynek reviewed May 17, 2026

View reviewed changes

Comment thread pmd-java/src/main/java/net/sourceforge/pmd/lang/java/rule/design/UseUtilityClassRule.java

UncleOwen added 4 commits May 21, 2026 18:35

Align JavaRuleUtil.isUtilityClass() with UseUtilityClass, add tests

8779a66

Changes in JavaRuleUtil.isUtilityClass() * Add support for nested classes * Abstract classes aren't utility classes * Classes with main() method aren't utility classes This was broken before and handled inconsistently

Align UseUtilityClass with JavaRuleUtil.isUtilityClass()

507f4d0

Changes in UseUtilityClass * Add support for initializers * Classes with main() method aren't utility classes * Remove special cases for JUnit3/4 suites - they are handled correctly by the current code.

Call JavaRuleUtil.isUtilityClass from UseUtilityClassRule

1562cc1

The implementations are identical.

Some minor fixes

4b6e158

UncleOwen force-pushed the issue-1102-Improve-consistency-of-utility-class-detection-across-rules branch from cb51ad0 to 4b6e158 Compare May 21, 2026 17:07

UncleOwen requested a review from zbynek May 24, 2026 16:52

[doc] Update release notes (pmd#1102)

7040597

adangel reviewed May 25, 2026

View reviewed changes

Update pmd-java/src/main/java/net/sourceforge/pmd/lang/java/rule/inte…

4a125ed

…rnal/JavaRuleUtil.java Co-authored-by: Andreas Dangel <andreas.dangel@adangel.org>

zbynek requested changes May 25, 2026

View reviewed changes

UncleOwen and others added 4 commits May 25, 2026 09:51

Update docs/pages/release_notes.md

edd4b53

Co-authored-by: Andreas Dangel <andreas.dangel@adangel.org>

fix c+p mistake in test

c3b8813

[doc] Update description of UseUtilityClass and ClassNamingConventions

dc4d47f

Update javadoc of JavaRuleUtil.isUtilityClass()

Nested interfaces/enums/records are implicitly static.

8ec11b7

Annotations are a thing.

c0dcbbd

adangel reviewed May 25, 2026

View reviewed changes

Comment thread pmd-java/src/main/resources/category/java/design.xml Outdated

adangel reviewed May 25, 2026

View reviewed changes

Comment thread pmd-java/src/test/java/net/sourceforge/pmd/lang/java/rule/internal/JavaRuleUtilTest.java Outdated

UncleOwen and others added 2 commits May 25, 2026 13:55

Update pmd-java/src/main/resources/category/java/design.xml

ab1a676

Co-authored-by: Andreas Dangel <andreas.dangel@adangel.org>

Enable disabled test

8fdaa02

adangel approved these changes May 25, 2026

View reviewed changes

UncleOwen merged commit e0e604a into pmd:main May 25, 2026
13 checks passed

UncleOwen deleted the issue-1102-Improve-consistency-of-utility-class-detection-across-rules branch May 25, 2026 15:25

UncleOwen added this to the 7.25.0 milestone May 25, 2026

UncleOwen mentioned this pull request May 26, 2026

[java] Rename UseUtilityClass #6714

Open

	For classes that only have static members, consider making them utility classes.
	Note that this doesn't apply to abstract classes, since their subclasses may
	well include non-static methods. Also, if you want this class to be a utility class,
	remember to add a private constructor to prevent instantiation.
	(Note, that this use was known before PMD 5.1.0 as UseSingleton).

	For this rule, a utility class is defined as: a concrete class that does not
	inherit from a super class or implement any interface and only has static fields
	or methods.

Uh oh!

Conversation

UncleOwen commented May 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Describe the PR

Related issues

Ready?

Uh oh!

pmd-actions-helper Bot commented May 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

zbynek commented May 24, 2026

Uh oh!

UncleOwen commented May 24, 2026

Uh oh!

UncleOwen commented May 24, 2026

Uh oh!

UncleOwen commented May 24, 2026

Uh oh!

UncleOwen commented May 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zbynek commented May 24, 2026

Uh oh!

UncleOwen commented May 24, 2026

Uh oh!

zbynek commented May 24, 2026

Uh oh!

adangel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zbynek left a comment

Choose a reason for hiding this comment

Uh oh!

UncleOwen commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

adangel left a comment

Choose a reason for hiding this comment

Uh oh!

UncleOwen commented May 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

UncleOwen commented May 17, 2026 •

edited

Loading

pmd-actions-helper Bot commented May 17, 2026 •

edited

Loading

UncleOwen commented May 24, 2026 •

edited

Loading

UncleOwen commented May 25, 2026 •

edited

Loading