Merge pull request #4754 from bergander:AllowCommentedBlocks

[java] EmptyControlStatementRule: Add allowCommentedBlocks property #4754

.all-contributorsrc

@@ -1667,7 +1667,8 @@
       "avatar_url": "https://avatars.githubusercontent.com/u/8858497?v=4",
       "profile": "https://github.com/bergander",
       "contributions": [
-        "bug"
+        "bug",
+        "code"
       ]
     },
     {

docs/pages/pmd/projectdocs/credits.md

@@ -812,7 +812,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
     <td align="center"><a href="https://github.com/b-3-n"><img src="https://avatars.githubusercontent.com/u/7460509?v=4?s=100" width="100px;" alt=""/><br /><sub><b>b-3-n</b></sub></a><br /><a href="https://github.com/pmd/pmd/issues?q=author%3Ab-3-n" title="Bug reports">🐛</a></td>
     <td align="center"><a href="https://github.com/balbhadra9"><img src="https://avatars.githubusercontent.com/u/43748088?v=4?s=100" width="100px;" alt=""/><br /><sub><b>balbhadra9</b></sub></a><br /><a href="https://github.com/pmd/pmd/issues?q=author%3Abalbhadra9" title="Bug reports">🐛</a></td>
     <td align="center"><a href="https://github.com/base23de"><img src="https://avatars.githubusercontent.com/u/37408753?v=4?s=100" width="100px;" alt=""/><br /><sub><b>base23de</b></sub></a><br /><a href="https://github.com/pmd/pmd/issues?q=author%3Abase23de" title="Bug reports">🐛</a></td>
-    <td align="center"><a href="https://github.com/bergander"><img src="https://avatars.githubusercontent.com/u/8858497?v=4?s=100" width="100px;" alt=""/><br /><sub><b>bergander</b></sub></a><br /><a href="https://github.com/pmd/pmd/issues?q=author%3Abergander" title="Bug reports">🐛</a></td>
+    <td align="center"><a href="https://github.com/bergander"><img src="https://avatars.githubusercontent.com/u/8858497?v=4?s=100" width="100px;" alt=""/><br /><sub><b>bergander</b></sub></a><br /><a href="https://github.com/pmd/pmd/issues?q=author%3Abergander" title="Bug reports">🐛</a> <a href="https://github.com/pmd/pmd/commits?author=bergander" title="Code">💻</a></td>
   </tr>
   <tr>
     <td align="center"><a href="https://github.com/berkam"><img src="https://avatars.githubusercontent.com/u/26228441?v=4?s=100" width="100px;" alt=""/><br /><sub><b>berkam</b></sub></a><br /><a href="https://github.com/pmd/pmd/commits?author=berkam" title="Code">💻</a> <a href="https://github.com/pmd/pmd/issues?q=author%3Aberkam" title="Bug reports">🐛</a></td>

docs/pages/release_notes.md

@@ -82,6 +82,11 @@ in the Migration Guide.
 * {% rule java/codestyle/UseExplicitTypes %} reports usages of `var` keyword, which was introduced with Java 10.
 * {% rule xml/bestpractices/MissingEncoding %} finds XML files without explicit encoding.
 
+**Changed Rules**
+
+* {% rule java/codestyle/EmptyControlStatement %}: The rule has a new property to allow empty blocks when
+  they contain a comment (`allowCommentedBlocks`).
+
 #### Fixed issues
 
 * cli
@@ -106,6 +111,7 @@ in the Migration Guide.
   * [#2847](https://github.com/pmd/pmd/issues/2847): \[java] New Rule: Use Explicit Types
   * [#4578](https://github.com/pmd/pmd/issues/4578): \[java] CommentDefaultAccessModifier comment needs to be before annotation if present
   * [#4645](https://github.com/pmd/pmd/issues/4645): \[java] CommentDefaultAccessModifier - False Positive with JUnit5's ParameterizedTest
+  * [#4754](https://github.com/pmd/pmd/pull/4754):   \[java] EmptyControlStatementRule: Add allowCommentedBlocks property
 * java-errorprone
   * [#4719](https://github.com/pmd/pmd/pull/4719):   \[java] UnnecessaryCaseChange: example doc toUpperCase() should compare to a capitalized string
 * javascript
@@ -136,6 +142,7 @@ The following previously deprecated classes have been removed:
 * [#4719](https://github.com/pmd/pmd/pull/4719): \[java] UnnecessaryCaseChange: example doc toUpperCase() should compare to a capitalized string - [ciufudean](https://github.com/ciufudean) (@ciufudean)
 * [#4738](https://github.com/pmd/pmd/pull/4738): \[doc] Added reference to the PMD extension for bld - [Erik C. Thauvin](https://github.com/ethauvin) (@ethauvin)
 * [#4750](https://github.com/pmd/pmd/pull/4750): \[core] Fix flaky SummaryHTMLRenderer - [219sansim](https://github.com/219sansim) (@219sansim)
+* [#4754](https://github.com/pmd/pmd/pull/4754): \[java] EmptyControlStatementRule: Add allowCommentedBlocks property - [Andreas Bergander](https://github.com/bergander) (@bergander)
 
 ### 🚀 Major Features and Enhancements
 
@@ -394,6 +401,8 @@ can be parsed now. PMD should now be able to parse Apex code up to version 59.0
   not necessary are allowed, if they separate expressions of different precedence.
   The other property `ignoreBalancing` (default: true) is similar, in that it allows parentheses that help
   reading and understanding the expressions.
+* {% rule java/codestyle/EmptyControlStatement %}: The rule has a new property to allow empty blocks when
+  they contain a comment (`allowCommentedBlocks`).
 
 **Java Design**
 
@@ -670,6 +679,7 @@ Language specific fixes:
     * [#4557](https://github.com/pmd/pmd/issues/4557): \[java] UnnecessaryImport FP with static imports of overloaded methods
     * [#4578](https://github.com/pmd/pmd/issues/4578): \[java] CommentDefaultAccessModifier comment needs to be before annotation if present
     * [#4645](https://github.com/pmd/pmd/issues/4645): \[java] CommentDefaultAccessModifier - False Positive with JUnit5's ParameterizedTest
+    * [#4754](https://github.com/pmd/pmd/pull/4754):   \[java] EmptyControlStatementRule: Add allowCommentedBlocks property
 * java-design
     * [#1014](https://github.com/pmd/pmd/issues/1014): \[java] LawOfDemeter: False positive with lambda expression
     * [#1605](https://github.com/pmd/pmd/issues/1605): \[java] LawOfDemeter: False positive for standard UTF-8 charset name
@@ -795,6 +805,7 @@ Language specific fixes:
 * [#4719](https://github.com/pmd/pmd/pull/4719): \[java] UnnecessaryCaseChange: example doc toUpperCase() should compare to a capitalized string - [ciufudean](https://github.com/ciufudean) (@ciufudean)
 * [#4738](https://github.com/pmd/pmd/pull/4738): \[doc] Added reference to the PMD extension for bld - [Erik C. Thauvin](https://github.com/ethauvin) (@ethauvin)
 * [#4750](https://github.com/pmd/pmd/pull/4750): \[core] Fix flaky SummaryHTMLRenderer - [219sansim](https://github.com/219sansim) (@219sansim)
+* [#4754](https://github.com/pmd/pmd/pull/4754): \[java] EmptyControlStatementRule: Add allowCommentedBlocks property - [Andreas Bergander](https://github.com/bergander) (@bergander)
 
 ### 📈 Stats
 * 5007 commits

pmd-java/src/main/java/net/sourceforge/pmd/lang/java/rule/codestyle/EmptyControlStatementRule.java

@@ -21,13 +21,25 @@
 import net.sourceforge.pmd.lang.java.ast.JavaNode;
 import net.sourceforge.pmd.lang.java.rule.AbstractJavaRulechainRule;
 import net.sourceforge.pmd.lang.java.rule.internal.JavaRuleUtil;
+import net.sourceforge.pmd.properties.PropertyDescriptor;
+import net.sourceforge.pmd.properties.PropertyFactory;
 
 public class EmptyControlStatementRule extends AbstractJavaRulechainRule {
 
+    private static final PropertyDescriptor<Boolean> ALLOW_COMMENTED_BLOCKS
+            = PropertyFactory.booleanProperty("allowCommentedBlocks")
+            .desc("Option for allowing empty but commented blocks. This is useful where a developer "
+                    + "wants to have the code structure and explain why a condition does not require "
+                    + "logic or to hold TODO comments for future work.")
+            .defaultValue(Boolean.FALSE)
+            .build();
+
     public EmptyControlStatementRule() {
         super(ASTFinallyClause.class, ASTSynchronizedStatement.class, ASTTryStatement.class, ASTDoStatement.class,
                 ASTBlock.class, ASTForStatement.class, ASTForeachStatement.class, ASTWhileStatement.class,
                 ASTIfStatement.class, ASTSwitchStatement.class, ASTInitializer.class);
+
+        definePropertyDescriptor(ALLOW_COMMENTED_BLOCKS);
     }
 
     @Override
@@ -145,7 +157,9 @@ public Object visit(ASTTryStatement node, Object data) {
     }
 
     private boolean isEmpty(JavaNode node) {
-        return node instanceof ASTBlock && node.getNumChildren() == 0
+        boolean allowCommentedBlocks = getProperty(ALLOW_COMMENTED_BLOCKS);
+
+        return (node instanceof ASTBlock && node.getNumChildren() == 0 && !(((ASTBlock) node).containsComment() && allowCommentedBlocks))
             || node instanceof ASTEmptyStatement;
     }
 }

pmd-java/src/test/resources/net/sourceforge/pmd/lang/java/rule/codestyle/xml/EmptyControlStatement.xml

@@ -228,7 +228,7 @@
             }
             ]]></code>
     </test-code>
-    
+
     <test-code>
         <description>empty initializer failure case (non static)</description>
         <expected-problems>1</expected-problems>
@@ -502,7 +502,8 @@ public class Foo {
     </test-code>
 
     <test-code>
-        <description>empty if statement with comment</description>
+        <description>empty if statement with comment, disallow commented block</description>
+        <rule-property name="allowCommentedBlocks">false</rule-property>
         <expected-problems>1</expected-problems>
         <expected-messages>
             <message>Empty if statement</message>
@@ -516,5 +517,21 @@ public class Foo {
     }
 }
         ]]></code>
+
+    </test-code>
+    <test-code>
+        <description>empty if statement with comment, allow commented block (#4754)</description>
+        <rule-property name="allowCommentedBlocks">true</rule-property>
+        <expected-problems>0</expected-problems>
+        <code><![CDATA[
+public class Foo {
+    void bar(int x) {
+        if (x == 0) {
+            // empty!
+        }
+    }
+}
+        ]]></code>
+
     </test-code>
 </test-data>