Issue checkstyle#14923: Improvements for language feature integration…

… documents

config/jsoref-spellchecker/whitelist.words

@@ -1151,6 +1151,7 @@ rq
 Rrridden
 RRRR
 Rsa
+RSPEC
 rtc
 Rtl
 ru

docs/NEW_LANGUAGE_FEATURE_INTEGRATION_PROCESS.md

@@ -1,63 +1,117 @@
-# New Language Feature Check Integration Process [WIP]
+# New Language Feature Check Integration Process
 
 The ability to parse new language features must be implemented and
-merged before following this document. This document outlines the procedures
+merged before following this document.
+
+Updating check modules and creating new checks to support new language features aligns Checkstyle
+with current best practices in the Java community and contributes to
+the project's ongoing evolution. This document outlines the procedures
 for integrating new language features into Checkstyle,
 by updating existing checks and creating new ones.
 
-## Check Update Procedure
+---
 
-Updating check modules to support new language features aligns Checkstyle
-with current best practices in the Java community
-and contributes to the project's ongoing evolution.
+## 1. Analyze Current Check Support for This Java Version
 
-### Java Enhancement Proposals (JEPS)
+### 1.1 Review Java Enhancement Proposals (JEPS)
 
 Review Java Enhancement Proposals (JEPS) related to the new feature.
 JEPS provide detailed information about the goals
 and motivations behind new language features.
 This information can help us understand the feature better and figure out
-which checks are most likely to be impacted.
+which checks are most likely to be impacted or what new checks might be needed.
+Key concepts to consider:
+
+- **Problem identification**: Understand what problem the new feature solves to build
+  insights about which checks are more likely to be impacted.
+
+- **Impact on Readability**: Assess whether the new feature enhances code readability.
+  Not all new features will necessarily improve readability, but if this one does,
+  Checkstyle can promote its use to enhance clarity and reduce verbosity.
 
 **Examples**:
 
-- For unnamed variables (`_`), the JEP guides us to recognize the new role of the
-  underscore for unnamed variables and avoid flagging the non-use of such variables.
-  Consequently, we should update `UnusedLocalVariableCheck` to ensure it does not
+- **Check updates**:  For unnamed variables (`_`), the JEP guides us to recognize the new role of
+  the underscore for unnamed variables and avoid flagging the non-use of such variables.
+  Consequently, we updated `UnusedLocalVariableCheck` to ensure it does not
   incorrectly violate unnamed variables.
 
-### Consider Similar and Related Tokens
+- **New checks**: Pattern Matching for `instanceof`, where the newer pattern matching feature
+  provides a more concise and type-safe alternative to traditional casting.
+  Ideally, we would consider creating a check
+  to suggest the use of this new feature if we see the typical `if X instanceof Y`
+  followed by a typecasting pattern.
+
+### 1.2 Consider Similar and Related Tokens
 
 Identify existing tokens that are similar to the new language feature tokens.
 This comparison helps to determine which existing checks may be relevant
 and require updates to support the new token. Additionally,
 we should consider the impact that a new child token may have
-on existing checks.
+on existing checks. By examining the acceptable tokens of existing checks and
+comparing them with the new tokens, you can determine which checks are likely to be impacted.
 
 **Examples**:
 
-- When the `RECORD_DEF` token was introduced, it was reasonable to look at all checks
-  that had `CLASS_DEF` in their acceptable tokens.
+- **Check updates**: When the `RECORD_DEF` token was introduced,
+ it was reasonable to look at all checks that had `CLASS_DEF` in their acceptable tokens.
 
-- When the `TEXT_BLOCK_CONTENT` token was introduced, it was reasonable to look at all checks
-  that had `STRING_LITERAL` in their acceptable tokens.
+- **Check updates**: When the `TEXT_BLOCK_CONTENT` token was introduced,
+  it was reasonable to look at all checks that had `STRING_LITERAL` in their acceptable tokens.
 
-- When switch expressions were introduced, it was reasonable to look at all checks
-  that deals with expressions because `LITERAL_SWITCH` may now fall under `EXPR` token.
+- **Check updates**: When switch expressions were introduced, it was reasonable to look at all
+  checks that deals with expressions because `LITERAL_SWITCH` may now fall under `EXPR` token.
   This requires analyzing the impact of this new child token on existing checks,
   such as `InnerAssignmentCheck`
 
-### Frequently Impacted Checks
+- **New checks**: When the `ENUM_DEF` token was introduced,
+  we examined checks that used `ARRAY_INIT` tokens and found that checks
+  like `NoArrayTrailingComma` were similar. However, it was determined that a new check,
+  `NoEnumTrailingComma`, was needed to handle enums.
+  We recommend creating separate checks because they handle different tokens
+  with distinct specifics, making configuration easier for users and allowing for
+  more tailored behavior.
+
+### 1.3 Frequently Impacted Checks
 
 Certain checks are most likely to be impacted by new language features.
 We should analyze the impact on the following frequently affected checks:
 
-- [IllegalToken](https://checkstyle.org/checks/coding/illegaltoken.html)
-- [IllegalTokenText](https://checkstyle.org/checks/coding/illegaltokentext.html)
-- [Indentation](https://checkstyle.org/checks/misc/indentation.html#Indentation)
-- [Whitespace](https://checkstyle.org/checks/whitespace/index.html)
+- [IllegalToken](https://checkstyle.org/checks/coding/illegaltoken.html): This check violates the
+  usage of specified tokens. Since new language features often introduce new tokens,
+  it's important to review this check.
+
+- [IllegalTokenText](https://checkstyle.org/checks/coding/illegaltokentext.html):
+  This check identifies and restricts customizable text patterns in the code.
+  New language features can provide programmers new ways to add custom text to
+  the code which would need to be scanned.
+
+- [Indentation](https://checkstyle.org/checks/misc/indentation.html#Indentation):
+  As new language features are introduced, it's important to ensure that they
+  follow proper indentation rules and that this check works as expected when executed on them.
+
+- [Whitespace](https://checkstyle.org/checks/whitespace/index.html):
+  This check impacts almost all language constructs by ensuring proper
+  use of whitespace before, after, or around them. As new language features
+  introduce new constructs, it's important to review and update this check.
+
+### 1.4 Discover Similar Checks
+
+Look for existing checks that address concepts
+similar to those introduced by the new language feature.
+These checks serve as references for designing and implementing new checks.
+
+**Examples**:
+
+- **Identifiers and Naming Conventions**: If the new feature introduces
+  new tokens involving identifiers, explore existing checks related to naming conventions.
+  We can create a new similar check to enforce naming conventions for the new feature.
+
+- **Sizes**: If we have a check that enforces a limit on the number of parameters
+  a method can have, we created a similar check for the number of record components
+  to ensure that records do not have an excessive number of components.
 
-### Review Other Static Analysis Tools
+### 1.5 Review Other Static Analysis Tools
 
 Examining how other static analysis tools handle new language features
 can provide valuable insights into best practices and potential pitfalls.
@@ -69,25 +123,25 @@ A list to a few of the popular ones:
 
 **Examples**:
 
-- IntelliJ IDEA introduced an inspection rule for Java 17 or higher to detect
+- **Check updates**: IntelliJ IDEA introduced an inspection rule for Java 17 or higher to detect
   redundant `strictfp` modifiers. This resulted in the analysis of `RedundantModifierCheck`
   to verify if we needed to update it.
 
-### Real Usage Examples in Large Projects
+- **New check**: Sonar introduced a [new rule](https://rules.sonarsource.com/java/tag/java21/RSPEC-6916/)
+  to suggest the use of `when` instead of a single if statement inside
+  a pattern match body. This resulted in the creation
+  of a new check `WhenShouldBeUsed` to enforce the use of this new feature.
+
+### 1.6 Real Usage Examples in Large Projects
 
 Review real usage examples of the new language feature in large projects.
 This helps to identify potential issues and ensures that the checks
 are aligned with practical use cases.
 A list of representative projects can be found
-[here](https://github.com/checkstyle/contribution/blob/master/checkstyle-tester/github-action-projects1.properties).
-
-## New Check Procedure
-
-Creating new checks for new language features helps us establish
-best practices within the community, ensuring that developers
-utilize these features effectively.
+[here](https://github.com/checkstyle/contribution/tree/master/checkstyle-tester)
+in projects files.
 
-### Good Source of Best Practices
+### 1.7 Good Source of Best Practices
 
 Identify a reliable source of best practices related to the new language feature.
 This could include official language documentation and community-driven style guides
@@ -97,48 +151,26 @@ such as:
 - [JetBrains blogs](https://blog.jetbrains.com/)
 - [Stackoverflow](https://stackoverflow.com/)
 
-### Review Associated JEP's Recommendations
-
-Refer to the associated JEPs for the new language feature.
-JEPs provide detailed insights into the design decisions,
-motivations and intended usage of the feature.
-Oftentimes, JEPs may solve a particular problem in the language,
-and we can create checks to suggest the use of these new features.
-Pay close attention to any recommendations provided in the JEPs
-as they can inform the development of effective new checks.
-
-**Examples**:
-
-- Pattern Matching for instanceof, where the newer pattern matching feature provides
-  a more concise and type-safe alternative to traditional casting.
-  Ideally, we would consider creating a check
-  to suggest the use of this new feature if we see the typical `if X instanceof Y`,
-  then typecasting pattern.
-
-### Discover Similar Checks
-
-Look for existing checks that address concepts
-similar to those introduced by the new language feature.
-These checks serve as references for designing and implementing new checks.
-
-**Examples**:
+---
 
-- **Identifiers and Naming Conventions**: If the new feature introduces
-  new tokens involving identifiers, explore existing checks related to naming conventions.
-  We can create a new similar check to enforce naming conventions for the new feature.
-
-## How to Create Tracker Issue
+## 2. How to Create Tracker Issue
 
 The tracker issue should document and share the results of the analysis
 conducted according to the outlined procedures in this document.
 It should include sections for each step of the analysis with the result
-of all of our actions. These tracker issues should be created for each
-new language feature, demonstrating our due diligence
+of all the actions done. These tracker issues should be created for each
+new language feature, demonstrating the team's due diligence
 in integrating the feature into Checkstyle.
+See [#14961](https://github.com/checkstyle/checkstyle/issues/14961) and
+[#14942](https://github.com/checkstyle/checkstyle/issues/14942) for reference.
+
+---
 
-## How to Open Child Issues
+## 3. How to Open Child Issues
 
-Using your findings from the tracker issue, open child issues for each check that needs
+Using the findings from the tracker issue, open child issues for each check that needs
 to be updated or for a new check related to the new language feature.
 This issue should be linked to the tracker issue of this feature.
 It is good to follow the bug report template to aid in demonstrating the need for check updates.
+See [#14963](https://github.com/checkstyle/checkstyle/issues/14963) and
+[#14985](https://github.com/checkstyle/checkstyle/issues/14985) for reference.