Create and Document Check Update Procedure for New Language Features

[nrmancuso]

When we add support for new language features, we always play a guessing game of what checks should be updated. While some heuristics will always be required, we can also have a procedure to follow to at least give is some direction and confidence that we have done our due diligence to fully support new language features. Adding the ability to parse new language features is really only the beginning of what we need to do.

As we have seen in the past, it is good to follow the bug report template to aid in demonstration of need for check updates.

We can call this document "New Language Feature Check Integration Process".

We need to create a document with the following outline:

• Check update procedure
  • How to discover checks that need to be updated, with examples
  • How to create a tracker issue for a feature/token (mention how we go through each discovery method and share results)
  • How to open child issues
  • Some checks will always be impacted, such as IllegalToken, and if the token has text (like String literals), IllegalTokenText
• New check procedure
  • Good sources of best practices
  • Discovery of similar checks (example: Some new token with identifiers will need some naming check), left and right curly
  • Review of associated JEPs to find pertinent information
  • openjdk mailing list (we need to figure out which one is best for this, can probably start figuring this out from a JEP)

Some sources of inspiration that I have used in the past for check discovery:

1. Consider similar tokens, i.e. for RECORD_DEF, it was reasonable to look at all checks that had CLASS_DEF in their acceptable tokens.

2. Similar constructs. An example of this would be constructors and methods.

3. JEPS themselves; they often have some recommendations about how to use new language features. Often times, JEPs may solve a particular problem in the language, and we can create checks to suggest to use these new features instead of the "old syntax". An example would be instanceof, where we avoid the cast by pattern matching.

4. Whitespace checks touch on most tokens

5. Examples in large codebases. To help facilitate this, we need to find some projects that use newer language features. Let's look through the new projects files in contribution that @Kevin222004 added last year. Example: https://github.com/checkstyle/contribution/blob/master/checkstyle-tester/github-action-projects1.properties

6. Review other static analysis tools (PMD, IDEA Inspections, spotbugs, etc.)

This document will live in the docs directory.

[nrmancuso]

@rnveach @mahfouz72 please share any additional check discovery methods that you can think of.

[mahfouz72]

These are all great methods, and I believe they should be sufficient to show us where updates should be made.

please share any additional check discovery methods that you can think of.

I think finding real usage examples in large codebases will be helpful. This may guide us in identifying potential violations and areas that require to be covered by checks

[rnveach]

One of the first steps is to find the JEPS and JLS for the new token.

Ensure document has number/letter points to be referenced later. Some linking to them would also be good.

Some checks will always be impacted. IllegalToken.

Similar constructs

Methods and constructors as an example.

Discovery of similar checks

Left and right curly.

Review of associated JEPs

Reviewing to find pertinent information to the current JEP

[mahfouz72]

another good method is to review similar static code analysis tools and IDE inspection rules for new features it may help us to identify potential check updates.

[nrmancuso]

@rnveach please add "approved" label if you are good