This post was authored by @opr18 (Thomas Roberts).
Currently, the standard reads:
Comments come before the code to which they refer, and should always be preceded by a blank line. Capitalize the first letter of the comment, and include a period at the end when writing full sentences. There must be a single space between the comment token (//) and the comment text.
The proposal is that the new wording should be:
Comments come before the code to which they refer, and should always be preceded by a blank line. Unless writing a linter override, or a `@see` type comment, capitalize the first letter of the comment, and include a period at the end. There must be a single space between the comment token (//) and the comment text.
The problem with the current guideline is that it is not enforceable by automated tools. It is hard for linting tools to easily distinguish between what is and isn’t a full sentence in the context of code comments.
Code reviews can quickly fill up with noisy comments and suggestions to capitalise or add periods to code comments. If this were fixable with a linting rule then these comments wouldn’t be necessary.
There are instances where it may not make sense to write in sentence case, for example: adding linter overrides or writing `see` comments where the comment may just be the name of a method or file, etc. so we would not enforce the rule on these types of comments.
If this guideline were to be amended, there would be several instances of code in the Gutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ repository alone that do not follow it. It would be necessary to create a PR that fixes all of these issues. Because the change only relates to comments, a single PR can be made addressing all instances of comments that don’t follow the guideline, because the rule relates to comments only, this would have no impact on functionality so minimal testing would be required.
Initially the rule could be enforced as a “warning” while the PR to fix the issues is completed and after it has been merged the rule could graduate to an “error”.
Here is a draft PR demonstrating the punctuation aspect of the proposed change: https://github.com/WordPress/gutenberg/pull/34964
As a part of next steps, this post is looking for feedback on:
- How do you feel about the proposed changes to the wording of the standard?
- Are there any concerns about the plan for implementing this change?
This proposal is open for feedback until October 5th, 2021 at which point a final decision will be made during #core-js office hours that day.