The WordPress coreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress. development team builds WordPress! Follow this site for general updates, status reports, and the occasional code debate. There’s lots of ways to contribute:
Found a bugbugA bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority.?Create a ticket in the bug tracker.
This is an important release which makes significant changes to improve the accuracy, performance, stability and maintainability of all sniffssniffA module for PHP Code Sniffer that analyzes code for a specific problem. Multiple stiffs are combined to create a PHPCS standard. The term is named because it detects code smells, similar to how a dog would "sniff" out food., as well as makes WordPressCS much better at handling modern PHPPHPThe web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher.
Most rules which were proposed in the Make post from March 2020 have been added to the Coding standards guidelines. Proposed rules which yielded a lot of discussion or to which objections were raised, have not been added. The intention is to publish separate Make posts for each of these over time, to discuss these more controversial proposals further.
For a large number of the new rules, sniffs have been added to WordPressCS to enforce these rules. More sniffs may be added in future WordPressCS releases to comprehensively cover the new and updated rules.
New architecture
WordPressCS previously had only one runtime dependency, which was PHP_CodeSniffer and end-users would need to manually register WordPressCS with PHP_CodeSniffer (or use a Composer pluginPluginA plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party to do so).
As of WordPressCS 3.0.0, WordPressCS will have four run-time dependencies and because of this, Composer will be the only supported way to install WordPressCS.
Mind: it is still perfectly possible to install WordPressCS and its dependencies without using Composer. It is just not an installation method for which support will be provided.
PHPCSUtils is a set of utility functions for use with PHP_CodeSniffer. PHPCSExtra is an additional set of sniffs. Composer Installer is a Composer plugin which will make sure that WordPressCS, PHPCSUtils as well as PHPCSExtra will be registered correctly with PHP_CodeSniffer.
New, non-WordPress-specific, sniffs will now be added to PHPCSExtra, while all WordPress-specific sniffs continue to be maintained in WordPressCS. Some of the pre-existing WordPressCS sniffs, which could benefit the wider PHP community, have been removed and replaced by similar (and improved!) sniffs which were added to PHPCSExtra.
Upgrading to WordPressCS 3.0.0
WordPressCS 3.0.0 contains breaking changes, both for people using ignore annotations, people maintaining custom rulesets, as well as for sniffsniffA module for PHP Code Sniffer that analyzes code for a specific problem. Multiple stiffs are combined to create a PHPCS standard. The term is named because it detects code smells, similar to how a dog would "sniff" out food. developers who maintain a custom PHPCSPHP Code SnifferPHP Code Sniffer, a popular tool for analyzing code quality. The WordPress Coding Standards rely on PHPCS. standard based on WordPressCS.
Please read the provided documentation carefully before you upgrade.
WordPress CoreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress. will upgrade to WordPressCS 3.0.0 in the near future as well. Follow TracTracAn open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress.ticketticketCreated for both bug reports and feature development on the bug tracker.#59161 if you want to stay informed and be sure to run composer update --with-all-dependencies once the patchpatchA special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing. has been committed to benefit from the latest & greatest sniff goodies.
Why did it take so long for this release to be “ready” ?
This release is basically the result of four big projects combined. It wasn’t necessarily the intention when work on WordPressCS 3.0.0 started that these projects would be combined into one release, but internal and external influences had an impact on timing, which made it so.
Also, please keep in mind that this project is basically maintained by a very, very small group of unpaid volunteers, who also have real jobs to do.
The four big projects we are talking about are:
A big refactor.
Adding new rules based on the Make post from March 2020.
Making the sniffs compatible with PHP 7.4, 8.0, 8.1 and 8.2 (* 8.2 in so far currently possible as PHP_CodeSniffer doesn’t fully support all 8.2 syntaxes yet).
Improving the available documentation.
Now let’s talk a little about each of these.
The refactor
WordPressCS previously had only one runtime dependency, which was PHP_CodeSniffer and end-users would need to manually register WordPressCS with PHP_CodeSniffer (or use a Composer plugin to do so). PHP_CodeSniffer offers some limited “utility” functions for sniffs and some basic abstracts.
But… WordPressCS – and other external standards, like PHPCompatibility – wanted more utility functions and better abstracts to be available, so these projects added their own and these utilities then had to be maintained in each of those projects.
Moving this work to a separate project was a setback and meant having to rework a lot. This separate project was published as PHPCSUtils in January 2020.
By that time, PHP 8.0 also started to come into play and it was becoming very clear that this would involve lots of changes for Coding Standards projects and both PHP_CodeSniffer, as well as the utilities, would have to be made compatible with PHP 8.0 before a new version of WordPressCS could be released.
In practical terms, most non-WordPress-specific utility functions are now available via PHPCSUtils. The remaining utility functions, i.e. the few exceptions + the WordPress-specific utilities, have all been moved to separate “helper” classes and traits to make the code more re-usable for sniffs not based on the WordPressCS specific base Sniff class.
New rules
The Make post from March 2020 proposed a lot of new rules, which resulted in a healthy discussion on the post and save for a few rules, most of the new rules met with approval.
This meant two things:
Research needed to be done whether there were any pre-existing sniffs that could be used to implement the approved rules.
For anything for which no sniff existed, a new sniff would need to be written.
A whopping 35 new sniffs were written for this release, 32 of these were added to PHPCSExtra, and 3 to WordPressCS itself.
To see a list of all the rules included in a particular standard, use:
vendor/bin/phpcs -e --standard=WordPress
(you can replace WordPress with, for instance, WordPress-Core or Universal or PSR12 to see the sniffs included in a particular standard)
Making sniffs compatible with PHP 7.4, 8.0, 8.1 (and 8.2)
Making a PHP project compatible with a new PHP version is one thing, doing so for a static analysis tool is something else altogether.
Making sniffs compatible with a new PHP version, basically involves three things:
Making sure the existing code will run on the new PHP version without errors or notices.
Making sure that sniffs do not throw a false positive/negative when confronted with a new syntax. Example: if a sniff looks for function calls to analyse and excludes method calls – function calls preceded by a -> or :: -, for PHP 8.0, these sniffs needed to be adjusted to also exclude function calls preceded by the nullsafe object operator ?->.
Add explicit support for new PHP features. Example: if a sniff would examine the name of a class-like structure, like a class, interface, or trait, the sniff would probably benefit from new code to also examine the names of PHP 8.1 enum structures.
Now, aside from 1, for 2 and 3, WordPressCS has a BIG dependency on PHP_CodeSniffer itself as PHP_CodeSniffer needs to support the new syntaxes first before an individual sniff can start to support them.
At the time work started for WordPressCS 3.0.0, PHP_CodeSniffer didn’t fully support PHP 7.4 yet, which added quite some new syntaxes and then PHP 8.0, 8.1 and 8.2 came along adding yet even more.
PHP 7.4, 8.0, 8.1, 8.2 added more new syntaxes to PHP than all of the PHP 5 and 7 releases before it combined.
Now you may ask yourself: “Why should the sniffs take all those new PHP syntaxes into account ?” After all, WordPress still supports PHP 7.0 (PHP 5.6 prior to WP 6.3), so those syntaxes cannot be used in code written for WordPress Core…
Well, the WordPress Coding StandardsWordPress Coding StandardsThe Accessibility, PHP, JavaScript, CSS, HTML, etc. coding standards as published in the WordPress Coding Standards Handbook.
May also refer to The collection of PHP_CodeSniffer rules (sniffs) used to format and validate PHP code developed for WordPress according to the PHP coding standards. are a community standard and WordPressCS codifies this into automated checks and as such, WordPressCS is not only used by WordPress Core, but also by the wider WordPress community, including agencies, plugin and theme authors etc. And plugins and themes may have a higher minimum supported PHP version, especially when we’re talking in-company/closed source plugins and themes.
Aside from that, sooner or later, WP will raise the minimum supported PHP version to a version including these new syntaxes, so the work would need to be done anyway and it’s easier to do this when what’s changed in PHP is still fresh in our minds.
So, a new waiting game started, where PHPCS needed to be updated first, then PHPCSUtils and only then could support for the new syntaxes be added to WordPressCS.
Safe for the PHP 8.2 Disjunctive Normal Form Types, which isn’t supported yet by PHP_CodeSniffer itself, all new syntaxes which were introduced in recent PHP versions are now taken into account in all sniffs in as far as our (my) imagination reached.
If you run into a situation where a sniff appears to not be fully compatible with modern PHP syntaxes yet, please open a bug report.
Improving the documentation
PHPCS has a built-in sniff documentation feature. Until recently, WordPressCS didn’t really support this feature and WordPress sniffs didn’t provide the documentation needed.
A start was made to add documentation to sniffs during the contributor dayContributor DayContributor Days are standalone days, frequently held before or after WordCamps but they can also happen at any time. They are events where people get together to work on various areas of https://make.wordpress.org/ There are many teams that people can participate in, each with a different focus. https://2017.us.wordcamp.org/contributor-day/https://make.wordpress.org/support/handbook/getting-started/getting-started-at-a-contributor-day/. at WordCampWordCampWordCamps are casual, locally-organized conferences covering everything related to WordPress. They're one of the places where the WordPress community comes together to teach one another what they’ve learned throughout the year and share the joy. Learn more. Europe 2019.
This effort has continued during the WordPressCS 3.0.0 cycle and the majority of sniffs used by and provided by WordPressCS now include documentation with code samples of what a sniff expects.
To view the documentation for any of the included standards use:
(you can replace WordPress with, for instance, WordPress-Core or Universal or PSR12 to see the documentation for other standards)
The future of WordPressCS
While WordPressCS is currently in a good place with this release, this won’t last long with the pace at which PHP is going.
WordPressCS 3.0.0 has costs thousands of hours of work and the vast majority of work has been done by one, mostly unpaid, contributor, with code review support from two fellow maintainers.
If we are being realistic, the bus factor of WordPressCS is 1, which is the most dangerous situation for any project to be in.
A large part of the WordPress community, including WordPress Core, relies heavily on the WordPress Coding Standards for code quality and security checks and while the community has been pretty vocal with copious complaints about the delayed release, barely anyone has stepped up and actually contributed.
The majority of the work for WordPressCS requires specialized knowledge. Knowledge which can be learned with enough time investment, but in recent years nobody has stepped up to do so.
This is an unsustainable situation and it ends now.
Unless funding is found to continue maintaining WordPressCS and its dependencies, the future is bleak and maintenance will be halted.
Let this be a call to action for the corporate/agency users of WordPressCS to come together and figure out a way to fund the continued maintenance and development of WordPressCS as that one person on which the whole project, including all dependencies, leans, is done with the current status quo.
If you want to help change this situation, please reach out to the WordPressCS maintainer team (@jrf, @GaryJ, @dingo_d) via WordPress SlackSlackSlack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. to discuss.
After discussion with several coreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress. committers and WordPress leads, the title and the contents of the text were changed to clarify that this is a proposal and not a decision set in stone.
Yoda conditions (or Yoda notation) is the programming style where the parts of an expression in the condition are reversed from the ‘typical’ order.
In a large part of the world, the natural reading order is left to right (LTR). This is what most programming languages adhere to. That means the variable assignments or echo/print statements are written with the variable first:
$post_type = 'post';
echo $post_type;
With the same idea in mind, conditions can also be written left to right, like:
The idea behind it is that writing the value on the left side of the condition will prevent accidentally assigning the value to the variable since assignments can’t be made to values.
While seemingly helpful at first glance, the obvious problem with them is the decreased readability of code, especially for people with reading disabilities such as dyslexia.
How we got here
When the handbook rule about Yoda conditions was introduced there was barely any static analysis tooling available in the PHPPHPThe web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher world. The only ‘foolproof’ way to prevent accidental assignment in conditions was to invert the order of the value being checked and the variable.
Automated checking for assignments in conditions via PHP_CodeSniffer (PHPCSPHP Code SnifferPHP Code Sniffer, a popular tool for analyzing code quality. The WordPress Coding Standards rely on PHPCS.), the underlying tooling for WPCSWPCSThe collection of PHP_CodeSniffer rules (sniffs) used to format and validate PHP code developed for WordPress according to the WordPress Coding Standards.
May also be an acronym referring to the Accessibility, PHP, JavaScript, CSS, HTML, etc. coding standards as published in the WordPress Coding Standards Handbook., became available in 2017. Moreover, the current sniffsniffA module for PHP Code Sniffer that analyzes code for a specific problem. Multiple stiffs are combined to create a PHPCS standard. The term is named because it detects code smells, similar to how a dog would "sniff" out food. enforcing Yoda condition in the WPCS doesn’t protect against accidental assignments in conditions.
Today there is tooling in place that can help with identifying assignments in conditions, making the Yoda rules obsolete.
Keep in mind that strict comparisons (===) are already strongly encouraged and a part of the WordPress-Core ruleset (warning), making accidental assignments even less likely.
A thorough analysis was made by Lucas Bustamante in the WPCS ticketticketCreated for both bug reports and feature development on the bug tracker. on the impact this could have on the plugins in the WordPress directory. The analysis showed that Yoda conditions are used in 18.02% of the plugins, so the majority of pluginPluginA plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party developers are using non-Yoda conditions.
What to do next?
The discussion in the WPCS ticket is long and opinionated, but comes down to these points:
Disallow Yoda condition
Drop the handbook rule that requires Yoda conditions and instead explicitly disallow using them.
Remove Yoda condition as a requirement
Discourage, but don’t disallow Yoda conditions. Just don’t report if the code is or is not using Yoda conditions. The rule would also be dropped from the handbook.
In both cases, assignments in conditions will still be checked for and forbidden.
Impact on the Core code
Disallowing Yoda conditions for WordPress Core would mean that all existing patches on open tickets for Core would need to be revisited and fixed accordingly, which could burden the contributors.
Running the same analysis as Lucas did for plugins, over the WordPress Core, there were 5427 Yoda conditions, and 312 non-Yoda conditions.
Luckily, these are violations that can be automatically fixed using phpcbf tool, but care should be taken to check if all the violations were correctly fixed.
If Yoda conditions are discouraged (option 2), and the existing Yoda conditions in the Core code remain, that would mean less work for the Core contributorsCore ContributorsCore contributors are those who have worked on a release of WordPress, by creating the functions or finding and patching bugs. These contributions are done through Trac. https://core.trac.wordpress.org., but also would add lots of inconsistencies in the Core code (mixed Yoda and non-Yoda conditions).
Next steps
The chosen way forward is to remove the Yoda condition as a requirement (remove it from the handbook) but not disallow it for the time being.
For WPCS, that would mean the removal of the Yoda conditions requirement (and sniff) in WPCS 3.0, with a notice that non-Yoda conditions will start to be required in WPCS 4.0 version.
Work is currently actively ongoing to prepare for the WPCS 3.0.0 release. There will be a minimum of six months between the 3.0.0 and the 4.0.0 release to allow time for Core and other projects to adjust.
Once WPCS 4.0.0 version is released, a one-time-only auto-fix of all the remaining Yoda conditions in Core will be made, and any patches to the Core which go in after that will have to use non-Yoda.
How to enforce the non-Yoda conditions in your code
If you are a WordPress plugin or theme developer, and you’d like to enforce non-Yoda conditions in your code, you can use the Generic.ControlStructures.DisallowYodaConditions sniff. In your phpcs.xml.dist file you should add the following sniff:
<?xml version="1.0"?>
<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="Example Project" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/squizlabs/PHP_CodeSniffer/master/phpcs.xsd">
<!-- Your custom rules. -->
<!-- Disallow Yoda conditions in your codebase. -->
<rule ref="Generic.ControlStructures.DisallowYodaConditions"/>
</ruleset>
If you want to change the Yoda conditions to non-Yoda conditions, use the phpcbf tool (part of PHPCS) with the Slevomat coding standards. Specifically, the SlevomatCodingStandard.ControlStructures.DisallowYodaComparison sniff that has the fixer for the Yoda conditions.
I propose switching to the original version of the Prettier code formatting tool in the GutenbergGutenbergThe 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/ project and updating it to the most recent 2.5 version. Consequently, we should apply the necessary changes to the existing WordPress JavaScript Coding Standards around spacing to respect Prettier’s capabilities.
Code formatting challenges
It’s worth reminding that this topic was discussed several times, beginning in 2017 when the initial exploration of using Prettier started with WordPress/gutenberg#2819. Throughout all that time, the Prettier maintainers didn’t change their mind about adding support for spaces between parens (()) and brackets ([]) despite many requests shared in prettier/prettier#1303 from users (including the WordPress community). That’s why we decided to apply the first batch of JavaScript Coding Standards revisions two years later to use the forked version of Prettier developed by developers at Automattic. It allowed us to remain aligned with the coding style conventions used for PHPPHPThe web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher in the WordPress codebase. In particular, to follow these rules:
Use spaces liberally throughout your code. “When in doubt, space it out.”
The WordPress JavaScriptJavaScriptJavaScript 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/. standards prefer slightly broader whitespace rules than the jQuery style guide. These deviations are for consistency between the PHP and JavaScript files in the WordPress codebase.
The issue is that we ended up with an outdated fork of Prettier in the Gutenberg project that didn’t get any updates for more than a year. The only motivation behind using a custom version of Prettier remains its additional functionality overriding formatting behavior for spaces around parens and brackets. In the meantime, there were three minor releases of Prettier with a long list of new features in the last year:
The Gutenberg project no longer uses only JavaScript for development. Some parts of the codebase use TypeScript, which we agreed upon a few months back. It means we can’t use improvements added for newer versions of the TypeScript language and potentially for future additions to the JavaScript language. A deprecation was also added to one of the config options we use in the shared Prettier config that the community uses. It turns out that it prevents using the @wordpress/prettier-config package with the most recent version of Prettier in 3rd party projects, as explained in WordPress/gutenberg#37516. Finally, we had multiple reports in WordPress/Gutenberg#21872 from the community members using @wordpress/scripts or @wordpress/eslint-plugin packages that the forked version of Prettier doesn’t install correctly in their projects. The good news is that switching to the original Prettier will resolve all of the above!
It quickly became noticeable that the automatic code formatting saves you so much time and energy when trying to keep a consistent coding style in the project. This is why we also started using Prettier to format other types of files it supports in the Gutenberg project, like JSONJSONJSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML., YAML, Markdown. We also consider doing the same for CSSCSSCascading Style Sheets. and SCSS next.
RevisionsRevisionsThe WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision. to JavaScript Coding Standards
I propose we apply all the necessary changes to the WordPress JavaScript Coding Standards to switch to the latest available version of Prettier (2.5 as of writing). The excerptExcerptAn excerpt is the description of the blog post or page that will by default show on the blog archive page, in search results (SERPs), and on social media. With an SEO plugin, the excerpt may also be in that plugin’s metabox. of the most significant revisions is included below.
-Some whitespace rules differ, for consistency with the WordPress PHP coding standards.
+Some whitespace rules differ, for consistency with the [Prettier](https://prettier.io) formatting tool.
-All new or updated JavaScript code will be reviewed to ensure it conforms to the standards, and passes JSHint.
+All new or updated JavaScript code will be reviewed to ensure it conforms to the standards, and passes [ESLint](https://eslint.org).
-Use spaces liberally throughout your code. “When in doubt, space it out.”
-Any ! negation operator should have a following space.*
+Any ! negation operator should not have a following space.
-Always include extra spaces around elements and arguments:
-array = [ a, b ];
-foo( arg );
-foo( 'string', object );
-foo( options, object[ property ] );
-foo( node, 'property', 2 );
-prop = object[ 'default' ];
-firstArrayElement = arr[ 0 ];
+Never include extra spaces around elements and arguments:
+arg = [a, b];
+foo(arg);
+foo('string', object);
+foo(options, object[property]);
+foo(node, 'property', 2);
+prop = object['default'];
+firstArrayElement = arr[0];
-var i;
-
-if ( condition ) {
- doSomething( 'with a string' );
-} else if ( otherCondition ) {
- otherThing( {
- key: value,
- otherKey: otherValue
- } );
-} else {
- somethingElse( true );
-}
-
-// Unlike jQuery, WordPress prefers a space after the ! negation operator.
-// This is also done to conform to our PHP standards.
-while ( ! condition ) {
- iterating++;
-}
-
-for ( i = 0; i < 100; i++ ) {
- object[ array[ i ] ] = someFn( i );
- $( '.container' ).val( array[ i ] );
-}
-
-try {
- // Expressions
-} catch ( e ) {
- // Expressions
-}
+var i;
+
+if (condition) {
+ doSomething('with a string');
+} else if (otherCondition) {
+ otherThing({
+ key: value,
+ otherKey: otherValue,
+ });
+} else {
+ somethingElse(true);
+}
+
+while (!condition) {
+ iterating++;
+}
+
+for (i = 0; i < 100; i++) {
+ object[array[i]] = someFn(i);
+ $('.container').val(array[i]);
+}
+
+try {
+ // Expressions
+} catch (e) {
+ // Expressions
+}
You can preview the impact on the Gutenberg codebase on GitHubGitHubGitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ in the exploratory Pull Request. The same changes would impact the tooling recommended for blockBlockBlock is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. development like @wordpress/create-block and @wordpress/scripts.
When will a decision be made?
Let’s plan for making a decision three five (updated on Jan 25th) weeks from the date of publication of this post. That should give enough time for discussion and questions.
This post was authored by @opr18 (Thomas Roberts).
During a recent WordPress #core-js meeting there was a discussion about updating the JavaScriptJavaScriptJavaScript 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 GutenbergGutenbergThe 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 coreCoreCore 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.
Until May last year, contributions to WordPress CoreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress. were bound to PHPPHPThe web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher 5.2 syntax and most plugins and themes stuck to the PHP 5.2 minimum requirement as well.
However, with the change to PHP 5.6 as the minimum PHP version for WordPress Core, new PHP features have become available for use in WP Core and with the outlook of a minimum version of PHP 7.x in the (near) future, even more interesting language features will soon become available for use in WordPress Core, plugins and themes.
With that in mind, we’d like to define coding standards for a number of these constructs and propose to implement automated checking for these in the WordPress Coding StandardsWordPress Coding StandardsThe Accessibility, PHP, JavaScript, CSS, HTML, etc. coding standards as published in the WordPress Coding Standards Handbook.
May also refer to The collection of PHP_CodeSniffer rules (sniffs) used to format and validate PHP code developed for WordPress according to the PHP coding standards. tooling in the near future.
While it may still be a while before some of these features will actually be adopted for use in WordPress Core, defining the coding standards in advance will allow for a consistent code base when they do get adopted and will allow for plugins and themes, which are not necessarily bound to the PHP 5.6 minimum, to safeguard their code consistency when they start using more modern PHP already.
To be honest, none of these proposals are terribly exciting and some may not even seem worth mentioning. Most follow either prior art in WordPress Core or industry standards for the same, but in the spirit of openness, we’d like to verify our take on these before implementing them.
You must be logged in to post a comment.