Add new ESLint rule to enforce comment case/punctuation

[opr]

Description

Note: I have never written an ESLint rule from scratch before, so any suggestions for improvement will be really appreciated

As part of the new proposal to amend the Coding Standards this PR adds a new custom ESLint rule that will find comments that don't terminate with a sentence-ending punctuation mark (!, ?, or .), comments that do not contain a space between the comment token and the first word, and comments where the first word is not capitalised.

I do not know if there's a way to detect if a comment is commented out code, or if it's just a regular inline comment.

This rule only targets comments of type Line and Block functions that start and terminate on the same line. It won't consider multi-line block comments.

The rule also considers whether a Line comment is followed or preceded directly by another comment. The reason for this is so comments of the below type are considered as one comment. The first and middle lines don't need to end with punctuation, and the middle and last line don't need to have capital letters. All lines do need to have spaces between the token and the words though.

// Some comments
// are split over
// multiple lines.

I also excludes comments that contain translators:, and @see or @todo type comments. There is a RegEx I used to check if comments were of this type: /translators:|@\w*\s/. In plain English this rule translates to "Any string containing translators or an @ sign followed immediately by a word and a whitespace character".

I have elected not to include an automatic fixer function to this. This is on the basis that it degrades the Developer Experience when it adds periods/spaces/capitals to commented out code. A situation where this could be annoying is when developing with Fix eslint errors on save enabled in your IDE, commenting/uncommenting lines of code becomes tedious when punctuation gets added.

How has this been tested?

There are ESLint tests that run against this rule.

To test this, you may also add a comment to a JavaScript file such as // My comment without punctuation and ensure that ESLint reports this as an error.

Screenshots

Types of changes

New feature/build tools modification

Checklist:

• My code is tested.
• My code follows the WordPress code style.
• My code follows the accessibility standards.
• I've tested my changes with keyboard and screen readers.
• My code has proper inline documentation.
• I've included developer documentation if appropriate.
• I've updated all React Native files affected by any refactorings/renamings in this PR (please manually search all *.native.js files for terms that need renaming or removal).

[github-actions]

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @opr! In case you missed it, we'd love to have you join us in our Slack community, where we hold regularly weekly meetings open to anyone to coordinate with each other.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

[opr]

I've created #36866 which applies fixes to all warnings on comments introduced by the rule addition in this PR.

The main purpose of doing that PR was to find exceptions to the rule.

I have added a regex for excluding various pragmas (think eslint-disable, @ts-ignore etc.) from being checked and flagged, and I have also added a regex for common words like iOS, iPad etc.

There is also now an exception to the rule where if your comment begins with an Identifier that appears on the next line, the capitalisation won't be enforced. There are some instances where variable names were capitalised though because they were a few lines below, rather than the line immediately after/before the comment. They have been fixed in #36866.

This PR now also only describes the @wordpress/comment-case rule as a warning, not an error.

[gziolo]

@opr impressive work 👏🏻

This PR now also only describes the @wordpress/comment-case rule as a warning, not an error.

I think that's a reasonable approach to give the rule some a few more months so it can mature. In the meantime we should observe whether we run into more edge cases 💯

Let's bring this PR in the #core-js channel on WordPress Slack to have more eyes looking at the final implementaiton. We could even land #36866 before that if we remove changes that are part of this PR 😄

[opr]

Thanks @gziolo, I'll be there in #core-js on 30th November to discuss this with everyone :) That's the next office hours, right?

We could even land #36866 before that if we remove changes that are part of this PR 😄

Great, I'll remove those parts and submit the PR for review. Thanks for your support on this!