This post was authored by @opr18 (Thomas Roberts).
During a recent WordPress #core-js meeting there was a discussion about updating the JavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. coding standard. The specific update that is being proposed is to change the rules relating to comments.
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.
WordPress core Core is the set of software required to run WordPress. The Core Development Team builds WordPress. currently uses JSHint for linting JavaScript files, and it does not appear that even the existing style guideline is enforced. Even so, if efforts were made to move to ESLint in WordPress core, implementing a fix for any comments that do not follow the standard should be straightforward.
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.
#coding-style, #codingstandards, #proposal
