Choose a single code formatter

[JustinBeckwith]

Throughout our various repositories, we use a variety of code formatters:

• Prettier
• Semistandard
• clang-format

Across TypeScript and JavaScript, samples and libraries, it would be ideal to standardize on a single one. My initial instinct is to use clang-format because it works well enough with gts, but I'm just tossing ideas. Thoughts?

Please vote your choice 😄

After this has at least 10 folks chiming in, we'll make a call.

[JustinBeckwith]

cc @GoogleCloudPlatform/node-team @GoogleCloudPlatform/yoshi-nodejs @jmdobry @fhinkel

[ofrobots]

clang-format is used by gts because that's what we use internally at Google for TypeScript code. It has the benefit that it works for other languages, and that internal and external Google code use the same format. The negatives are that it is relatively inflexible, is very very slow to pick up new features (e.g. ability to format TSX code), is written in C++, and shipped as a binary that doesn't work in all environments node works.

I would be open to a suggestion of changing the default formatter in gts if we have strong motivation to do so.

I think one of the most fundamental requirements is that the formatter should be able to support both JS and TS. Based on that criteria only prettier and clang-format are contenders AFAIK.

[JustinBeckwith]

Honestly, clang-format has mostly just stayed out of my way. I would be personally happier with prettier, but I don't think I have any actual good reasons at this stage to switch.

I voted above to switch everything to clang, but want to hear from everyone.

@jmdobry @fhinkel @crwilcox @kinwa91 @theacodes @alexander-fenster

[JustinBeckwith]

Making sure @stephenplusplus and @callmehiphop get to chime in here as well :)

[ofrobots]

One more negative for clang-format is that it is not human-friendly. If there are style errors, it outputs XML rather than human readable error messages. Now it could be argued that one should never need to look at the formatting errors, but I am still not sure if that excuses the user-unfriendliness.

[kjin]

I like prettier as a format better, but like @ofrobots said there is the benefit of being consistent internal and external to Google. I haven't seen a full evaluation of how important that is to us though.

Re: Inflexibility, aren't we (Google) the authors of our own clang-format style? Can we influence the changes there?

[ofrobots]

Re: Inflexibility, aren't we (Google) the authors of our own clang-format style? Can we influence the changes there?

In theory yes. In practice, most of the folks on this thread (that have a stake in this) are much more likely to contribute changes to a JS/TS project rather than one written in C++. AFAIK, TS support in clang-format is maintained mostly single-handedly (by @mprobst). Things like TSX support, e.g., are probably not high in the priority list for internal Google stuff, but may be important for external users and for docs and samples we provide for Google Cloud.

[mprobst]

There are two things - changing clang-format style (e.g. in bin packing, brace spacing, etc), and adding support for more languages.

The tricky bit about changing the style is that it's often hard to find a formatting style that is accepted by at least the large majority of users. I personally don't actually care all that much - as long as it's not eye bleeding terrible, I'm happy to have some consistent style that's automatically enforced. But some people care a lot, and clang-format should cater to those users. We're handling that mostly on a case by case basis.

The other question is stuff like adding TSX support. clang-format formats many different languages (C++, Java, proto buffers, etc), and is based on LLVM's clang project, i.e. at the very base on a C++ lexer. That's working surprisingly well, but adding support for entirely different lexing environments, such as TSX's HTML content, would be a major project, and more than we currently want to invest I'm afraid.

I wouldn't actually be opposed to replacing our use of clang-format with prettier. We looked into it a bit though, and there are a number of issues that'd make it hard. There are a few breaking issues, such as prettier de-quoting quoted properties, which breaks Closure Compiler optimizations, but also just a long list of style differences that somebody would need to work through and reconcile with Google's JavaScript and TypeScript style. Again, possible, but also a lot of work that's hard to justify, given that clang-format currently mostly works for our use cases.

Does that make sense?

[carnesen]

Hi Everybody! A few months ago I was tasked with defining the /\.[jt]sx?$/ code style strategy for Ameriprise Financial. These days I'm funemployed and pitching in on these @google-cloud open-source Node.js projects. Please allow me to share my thoughts.

It's important to remember that eslint and tslint are code formatters too via their "--fix" flag. Linting and formatting tools should be considered at the same time because they have so much overlap in both functionality and developer workflow.

As a developer, I expect to be able to fix most lint+format errors both:

1. Using a single command-line interface (CLI) command
2. Automatically on "save" for a file I'm editing in my IDE/editor

For my two cents, the pattern that these @google-cloud projects use for .js files works great on both counts. For a concrete example see nodejs-dns. The short story is that we use
eslint-config-prettier to disable in eslint "all rules that are unnecessary or might conflict with Prettier". We don't use the prettier CLI for formatting (see e.g. googleapis/nodejs-dns#116). Instead, we use eslint-plugin-prettier, which reports Prettier diffs as eslint errors. The "fix" CLI command is as simple as eslint --fix, and of course any editor worth its bytes has solid eslint integration with auto-fix-on-save.

Unfortunately, the pattern we use for .ts files isn't great on either count! The short story is that we've developed our own home-grown linter+formatter for TypeScript, gts, based on tslint and clang-format. As a CLI, gts falls short of my expectations. It's not terrible; it's just not as sophisticated, featureful, and bug-free as something like tslint, eslint, or react-scripts-ts. See google/gts#211 and google/gts#212, for example. As for IDE support, I eventually figured out the secret sauce for auto-fix-on-save in Visual Studio Code, but it wasn't easy.

In addition to these workflow shortcomings, I'd consider any of the following on its own to be a "deal breaker", bad enough that I would strongly advise against any individual or organization adopting gts (including Google!) in its current form as their standard for TypeScript formatting. clang-format:

• Produces broken code
• Produces difficult-to-read code
• Doesn't support .tsx: See this issue and @ofrobot's comment above
• Lacks community support: Relative to Prettier by any metric (stars, contributors, downloads, ...), clang-format is obscure/unknown/unused in the TypeScript community. As I understand it from @ofrobots, "TS support in clang-format is maintained mostly single-handedly (by @mprobst)".

I'm not qualified to weigh the arguments in favor of clang-format because they all seem to be internal to Google. For me and for any of the half-dozen organizations I've worked at in my decade in software though, Prettier would be the better choice by very wide margin.

My recommendation is to adopt for .tsx? files the same pattern that we use for .js files but with "es" replaced by "ts". That is to say that our tslint configuration should "extend" tslint-config-prettier and enable Prettier formatting via tslint-plugin-prettier. The "fix" CLI command could be as simple as "tslint --fix", and of course any editor worth its bytes has solid tslint integration with auto-fix-on-save. In this scenario, gts would still house the shared tslint and tsconfig configurations, but we could simplify its "fix" and "check" verbs to be thin wrappers around tslint.

[carnesen]

ts-style has switched to prettier google/gts#259

[JustinBeckwith]

This is actually complete 🥂