Coding Standards ECMAScript - adamconroy/ECMAScript_style_proposal GitHub Wiki

Philosophy and High Level Implementation

Due to the highly collaborative nature of working in open source in the JavaScript community it is best to be consistent and conform to the most common standards. The most comprehensive JavaScript coding standard that is often referenced by some of the larger open source projects out there is the Google JavaScript Style Guide.

It is recommended to read the Google Style Guide to get an understanding of most of the things that can be opinionated-ly styled in JavaScript and have a strong basis for understanding what our JavaScript should look like. This will be very helpful in quickly reading and understanding the code that is checked in as well as allowing the programmer to more easily write code that is consistent with the code that they are integrating with. However, we do not rely solely on the programmer to type properly styled code.

For that, we have:

Prettier

Prettier is a unique tool in that it isn't a linter or "just" a code formatter. It is extremely opinionated and has very few options. It takes user error and user specific tools (different IDEs/editors) out of the equation and explicity streams and writes files that all consistently conform. Users will note that it does not perfectly conform to the Google Style Guide but it is very close such that a user who understands the Style Guide won't be lost with the small differences that Prettier makes.

Optional: List notable differences between the Google Style Guide and Prettier's output

For users unfamiliar with Prettier it is recommended to read their About Section to understand why they developed it how they did and understand why we use it.

Using Prettier

Because RStudio isn't currently written primarily in JavaScript with a JS-centric build process and because we have numerous JS files that are integrated in various ways (perhaps we want to leave them as is) it is up to the programmer's discretion how they want to integrate Prettier into their workflow. However, for entirely RStudio created and managed ECMAScript files Prettier usage is mandatory.

The easiest way to use Prettier is to integrate it into your editor. Most popular editors are supported. Ensure that you explicitly install the Prettier version listed in the package.json file in the base RStudio path (this may be updated but it requires team wide sign-off and effort). With the plugin editor integration you can format on save and fire and forget. Note that there may be some files that you may not want Prettier to format, for this case most plugins support disabling auto-format with a quick toggle.

If you prefer to operate only through the CLI Prettier operates as a powerful tool that you can script with fairly fine grained control.

While it can be configured with a git pre-commit hook this can become messy due to the way that hooks pseudo-live outside of git and can become maintenance targets. Also, due to our unique infrastructure, it would require a fair amount of customization.

We use the default Prettier configuration with no option flags.

TypeScript

Prettier also just works for TypeScript but programmers will benefit from reading the Angular Style Guide to become familiar with some of the differences in style that TypeScript brings to the table.