Proposal: Changes to JavaScript Coding Standards for Full Prettier Compatibility

I propose switching to the original version of the Prettier code formatting tool in the GutenbergGutenberg 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/ 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 PHPPHP The 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 JavaScriptJavaScript 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/. 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 JSONJSON JSON, 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 CSSCSS Cascading Style Sheets. and SCSS next.

RevisionsRevisions The 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 excerptExcerpt An 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 GitHubGitHub GitHub is a website that offers online implementation of git repositories that can 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 blockBlock Block 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.

#coding-style, #codingstandards, #javascript