From 65defd25880ebbc01a36d0f030f23995dc2279be Mon Sep 17 00:00:00 2001 From: Simon Lydell Date: Sat, 3 Nov 2018 10:06:23 +0100 Subject: [PATCH 1/6] Update rationale about multiline object literals for the 1.15 changes --- docs/rationale.md | 43 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/docs/rationale.md b/docs/rationale.md index 4e0d363a6e87..9dda878a4822 100644 --- a/docs/rationale.md +++ b/docs/rationale.md @@ -28,7 +28,48 @@ It turns out that empty lines are very hard to automatically generate. The appro ### Multi-line objects -By default, Prettier’s printing algorithm prints expressions on a single line if they fit. Objects are used for a lot of different things in JavaScript, though, and sometimes it really helps readability if they stay multiline. See [object lists], [nested configs], [stylesheets] and [keyed methods], for example. We haven't been able to find a good rule for all those cases, so Prettier instead keeps objects multiline if there's a newline anywhere inside it in the original source code. A consequence of this is that long singleline objects are automatically expanded, but short multiline objects are never collapsed. +By default, Prettier’s printing algorithm prints expressions on a single line if they fit. Objects are used for a lot of different things in JavaScript, though, and sometimes it really helps readability if they stay multiline. See [object lists], [nested configs], [stylesheets] and [keyed methods], for example. We haven't been able to find a good rule for all those cases, so Prettier instead keeps objects multiline if there's a newline between the `{` and the first key in the original source code. A consequence of this is that long singleline objects are automatically expanded, but short multiline objects are never collapsed. + +**Tip:** If you have a multiline object that you'd like to join up into a single line: + +```js +const user = { + name: "John Doe", + age: 30 +}; +``` + +…all you need to do is remove the newline after `{`: + + +```js +const user = { name: "John Doe", + age: 30 +}; +``` + +…and then run Prettier: + +```js +const user = { name: "John Doe", age: 30 }; +``` + +And if you'd like to go multiline again, add in a newline after `{`: + + +```js +const user = { + name: "John Doe", age: 30 }; +``` + +…and run Prettier: + +```js +const user = { + name: "John Doe", + age: 30 +}; +``` [object lists]: https://github.com/prettier/prettier/issues/74#issue-199965534 [nested configs]: https://github.com/prettier/prettier/issues/88#issuecomment-275448346 From 18d48643591c79b03d5f357310cdcbdda1203eb4 Mon Sep 17 00:00:00 2001 From: Simon Lydell Date: Sat, 3 Nov 2018 10:26:07 +0100 Subject: [PATCH 2/6] Add rationale about decorators for the 1.15 changes --- docs/rationale.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/docs/rationale.md b/docs/rationale.md index 9dda878a4822..3cdbffd7af6d 100644 --- a/docs/rationale.md +++ b/docs/rationale.md @@ -76,6 +76,57 @@ const user = { [stylesheets]: https://github.com/prettier/prettier/issues/74#issuecomment-275262094 [keyed methods]: https://github.com/prettier/prettier/pull/495#issuecomment-275745434 +### Decorators + +Just like with objects, decorators are used for a lot of different things. Sometimes it makes sense to write decorators _above_ the line they're decorating, sometimes it's nicer if they're on the _same_ line. We haven't been able to find a good rule for this, so Prettier keeps your decorator positioned like you wrote them (if they fit on the line). This isn't ideal, but a pragmatic solution to a difficult problem. + +```js +@Component({ + selector: "hero-button", + template: `` +}) +export class HeroButtonComponent { + // These decorators were written inline and fit on the line so they stay + // inline. + @Output() change = new EventEmitter(); + @Input() label: string; + + // These were written multiline, so they stay multiline. + @readonly + @nonenumerable + NODE_TYPE: 2; +} +``` + +There's one exception: classes. We don't think it ever makes sense to inline the decorators for them, so they are always moved to their own line. + + +```js +// Before running Prettier: +@observer class OrderLine { + @observable price: number = 0; +} +``` + +```js +// After running Prettier: +@observer +class OrderLine { + @observable price: number = 0; +} +``` + +Note: Prettier 1.14.x and older tried to automatically move your decorators, so if you've run an older Prettier version on your code you might need to manually join up some decorators here and there to avoid inconsistencies: + +```js +@observer +class OrderLine { + @observable price: number = 0; + @observable + amount: number = 0; +} +``` + ### Semicolons This is about using the [`--no-semi`](options.md#semicolons) option. From 386cee47c303988ac3f21e8207632028298dc7fa Mon Sep 17 00:00:00 2001 From: Lipis Date: Sun, 4 Nov 2018 18:04:44 +0200 Subject: [PATCH 3/6] Lint with Prettier --- docs/rationale.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/rationale.md b/docs/rationale.md index 3cdbffd7af6d..32e028fcf3c6 100644 --- a/docs/rationale.md +++ b/docs/rationale.md @@ -88,8 +88,10 @@ Just like with objects, decorators are used for a lot of different things. Somet export class HeroButtonComponent { // These decorators were written inline and fit on the line so they stay // inline. - @Output() change = new EventEmitter(); - @Input() label: string; + @Output() + change = new EventEmitter(); + @Input() + label: string; // These were written multiline, so they stay multiline. @readonly @@ -112,7 +114,8 @@ There's one exception: classes. We don't think it ever makes sense to inline the // After running Prettier: @observer class OrderLine { - @observable price: number = 0; + @observable + price: number = 0; } ``` @@ -121,7 +124,8 @@ Note: Prettier 1.14.x and older tried to automatically move your decorators, so ```js @observer class OrderLine { - @observable price: number = 0; + @observable + price: number = 0; @observable amount: number = 0; } From eb7b6b065a94a78346b55d39a802ef53e4b48899 Mon Sep 17 00:00:00 2001 From: Lipis Date: Sun, 4 Nov 2018 18:06:23 +0200 Subject: [PATCH 4/6] Rollback --- docs/rationale.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/rationale.md b/docs/rationale.md index 32e028fcf3c6..3cdbffd7af6d 100644 --- a/docs/rationale.md +++ b/docs/rationale.md @@ -88,10 +88,8 @@ Just like with objects, decorators are used for a lot of different things. Somet export class HeroButtonComponent { // These decorators were written inline and fit on the line so they stay // inline. - @Output() - change = new EventEmitter(); - @Input() - label: string; + @Output() change = new EventEmitter(); + @Input() label: string; // These were written multiline, so they stay multiline. @readonly @@ -114,8 +112,7 @@ There's one exception: classes. We don't think it ever makes sense to inline the // After running Prettier: @observer class OrderLine { - @observable - price: number = 0; + @observable price: number = 0; } ``` @@ -124,8 +121,7 @@ Note: Prettier 1.14.x and older tried to automatically move your decorators, so ```js @observer class OrderLine { - @observable - price: number = 0; + @observable price: number = 0; @observable amount: number = 0; } From abd51fd47583a47c734a7ffad597afe4dc6986ad Mon Sep 17 00:00:00 2001 From: Simon Lydell Date: Mon, 5 Nov 2018 09:20:42 +0100 Subject: [PATCH 5/6] Clarify decorator + export + class --- docs/rationale.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/rationale.md b/docs/rationale.md index 3cdbffd7af6d..e69ea292c11e 100644 --- a/docs/rationale.md +++ b/docs/rationale.md @@ -85,7 +85,7 @@ Just like with objects, decorators are used for a lot of different things. Somet selector: "hero-button", template: `` }) -export class HeroButtonComponent { +class HeroButtonComponent { // These decorators were written inline and fit on the line so they stay // inline. @Output() change = new EventEmitter(); @@ -127,6 +127,15 @@ class OrderLine { } ``` +One final thing: TC39 has [not yet decided if decorators come before or after `export`](https://github.com/tc39/proposal-decorators/issues/69). In the meantime, Prettier supports both: + +```js +@decorator +export class Foo { } + +export @decorator class Foo { } +``` + ### Semicolons This is about using the [`--no-semi`](options.md#semicolons) option. From c77520e1db2267a1c1ccd89c05dd22f6f96929ea Mon Sep 17 00:00:00 2001 From: Simon Lydell Date: Mon, 5 Nov 2018 09:56:56 +0100 Subject: [PATCH 6/6] Update rationale and option philosophy for jsx quotes --- docs/option-philosophy.md | 3 ++- docs/rationale.md | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/option-philosophy.md b/docs/option-philosophy.md index 9364a78e959d..5f86637ff08b 100644 --- a/docs/option-philosophy.md +++ b/docs/option-philosophy.md @@ -19,7 +19,8 @@ Then there's a bunch of interesting cases. - `--trailing-comma es5` was added to make it easier to use trailing commas in most environments without having to transpile (trailing function commas were added in ES2017). - `--prose-wrap` is important to support all quirky markdown renderers in the wild. -- `--arrow-parens` was added after [huge demand](https://github.com/prettier/prettier/issues/812). Prettier has to strike a balance between ideal goals and listening to the community. +- `--arrow-parens` was added after – at the time – [huge demand](https://github.com/prettier/prettier/issues/812). Prettier has to strike a balance between ideal goals and listening to the community. +- `--jsx-single-quote` was also added after [great demand](https://github.com/prettier/prettier/issues/1080), but after more consideration. It took quite some time to figure out the right approach. - `--jsx-bracket-same-line` was needed for a big company with a huge code base (Facebook), which backed the project when it got started, to be able to [adopt Prettier at all](https://github.com/prettier/prettier/pull/661#issuecomment-295770645). Finally, perhaps the most interesting of them all is `--bracket-spacing`. diff --git a/docs/rationale.md b/docs/rationale.md index e69ea292c11e..ca7132dddfba 100644 --- a/docs/rationale.md +++ b/docs/rationale.md @@ -15,7 +15,8 @@ The first requirement of Prettier is to output valid code that has the exact sam Double or single quotes? Prettier chooses the one which results in the fewest number of escapes. `"It's gettin' better!"`, not `'It\'s gettin\' better!'`. In case of a tie, Prettier defaults to double quotes (but that can be changed via the [`--single-quote`](options.html#quotes) option). -JSX always uses double quotes. JSX takes its roots from HTML, where the dominant use of quotes for attributes is double quotes. Browser developer tools also follow this convention by always displaying HTML with double quotes, even if the source code uses single quotes. +JSX has its own option for quotes: [`--jsx-single-quote`](options.html#jsx-quotes). +JSX takes its roots from HTML, where the dominant use of quotes for attributes is double quotes. Browser developer tools also follow this convention by always displaying HTML with double quotes, even if the source code uses single quotes. A separate option allows using single quotes for JS and double quotes for "HTML" (JSX). Prettier maintains the way your string is escaped. For example, `"🙂"` won't be formatted into `"\uD83D\uDE42"` and vice versa.