Coding standards have been a recurring topic in the JavaScript Weekly Chat over the past few months. One rule in particular which has been the focus of much discussion are the exceptions for whitespace in arrays and function calls, which reads:
Always include extra spaces around elements and arguments:
[…]
Exceptions:
- […] do not include a space around string literals or integers used as key values in array notation
- Function with a callback, object, or array as the sole argument: No space on either side of the argument
- Function with a callback, object, or array as the first argument: No space before the first argument
- Function with a callback, object, or array as the last argument: No space after after the last argument
In the course of our chats, there has been some consensus around removing this “Exceptions” section entirely, though we considered to seek broader feedback on the decision, particularly in how it impacts overlapping PHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher standards and existing code.
Why should this exception be removed?
The purpose of a coding standard should be to impose sensible rules for the sake of consistency and readability. In the case of consistency, a developer should be at ease both in writing and reading code.
The very existence of an exception is at odds with these ideals, harming consistency in that:
- A code reader may not think to expect it if they are not familiar with the exception
- A code writer may not know to apply it if they are not familiar with the exception. Or worse yet, one familiar with the rule may not know how to apply it.
The arrays and functions exception is notably egregious for being difficult to apply. Take, for example, the following snippet of code:
( function( wp ) {
wp.foo = foo( 5, {});
wp.bar(function() {
console.log( 'Done' );
});
wp.baz( x, x + 5 );
wp.baz(x => x + 5);
} )( window.wp = window.wp || {} );
This code is valid in its use of whitespace, but took considerable effort on the part of a developer well-versed in the standards to understand precisely where the exceptions do and do not apply.
Generally, exceptions increase the barrier to entry for new developers by imposing another prerequisite to becoming productive, increase overhead for existing contributors by requiring careful consideration of their application, and are anti-productive in the review hours wasted enforcing their inevitable mis-use.
Why should this exception not be removed?
All of the above notwithstanding, the exceptions concerning array or object keys at least have some basis in overlap with equivalent rules in the PHP Coding Standards. While I would argue that most all exceptions should be avoided, the focus of the first section is aimed primarily at function arguments, which tends to cause most uncertainty. It may be an agreeable compromise to remove only the exceptions impacting function arguments, leaving still the array and object key exceptions.
Standards changes should be carefully considered, as it has a large impact on existing code which applies the current standard, and on knowledge of developers who have already become familiar with the standards. However, my experience is that these exceptions aren’t particularly well-understood, and in-fact that eliminating them would be more in spirit with how whitespace is otherwise applied (“When in doubt, space it out.”).
What happens next if these exceptions are removed?
If consensus is reached, the following actions should be taken:
- Our standards documentation are updated to remove the exception language
- Our ESLint rules are updated to remove the exception
- All new commits to WordPress core Core is the set of software required to run WordPress. The Core Development Team builds WordPress. follow the new standards
- Old code will only be refactored as part of a larger, codebase wide refactoring effort (see related effort at #41057)
What are your thoughts? Please share in the comments below.
#javascript, #standards
