Skip to content

Commit e036251

Browse files
lydellikatyang
lydell
authored and
ikatyang
committed
Update rationale for the 1.15 changes (#5332)
1 parent 514b6d3 commit e036251

2 files changed

Lines changed: 106 additions & 3 deletions

File tree

‎docs/option-philosophy.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@ Then there's a bunch of interesting cases.
1919

2020
- `--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).
2121
- `--prose-wrap` is important to support all quirky markdown renderers in the wild.
22-
- `--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.
22+
- `--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.
23+
- `--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.
2324
- `--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).
2425

2526
Finally, perhaps the most interesting of them all is `--bracket-spacing`.

‎docs/rationale.md‎

Lines changed: 104 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,8 @@ The first requirement of Prettier is to output valid code that has the exact sam
1515

1616
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).
1717

18-
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.
18+
JSX has its own option for quotes: [`--jsx-single-quote`](options.html#jsx-quotes).
19+
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).
1920

2021
Prettier maintains the way your string is escaped. For example, `"🙂"` won't be formatted into `"\uD83D\uDE42"` and vice versa.
2122

@@ -28,13 +29,114 @@ It turns out that empty lines are very hard to automatically generate. The appro
2829

2930
### Multi-line objects
3031

31-
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.
32+
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.
33+
34+
**Tip:** If you have a multiline object that you'd like to join up into a single line:
35+
36+
```js
37+
const user = {
38+
name: "John Doe",
39+
age: 30
40+
};
41+
```
42+
43+
…all you need to do is remove the newline after `{`:
44+
45+
<!-- prettier-ignore -->
46+
```js
47+
const user = { name: "John Doe",
48+
age: 30
49+
};
50+
```
51+
52+
…and then run Prettier:
53+
54+
```js
55+
const user = { name: "John Doe", age: 30 };
56+
```
57+
58+
And if you'd like to go multiline again, add in a newline after `{`:
59+
60+
<!-- prettier-ignore -->
61+
```js
62+
const user = {
63+
name: "John Doe", age: 30 };
64+
```
65+
66+
…and run Prettier:
67+
68+
```js
69+
const user = {
70+
name: "John Doe",
71+
age: 30
72+
};
73+
```
3274

3375
[object lists]: https://github.com/prettier/prettier/issues/74#issue-199965534
3476
[nested configs]: https://github.com/prettier/prettier/issues/88#issuecomment-275448346
3577
[stylesheets]: https://github.com/prettier/prettier/issues/74#issuecomment-275262094
3678
[keyed methods]: https://github.com/prettier/prettier/pull/495#issuecomment-275745434
3779

80+
### Decorators
81+
82+
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.
83+
84+
```js
85+
@Component({
86+
selector: "hero-button",
87+
template: `<button>{{label}}</button>`
88+
})
89+
class HeroButtonComponent {
90+
// These decorators were written inline and fit on the line so they stay
91+
// inline.
92+
@Output() change = new EventEmitter();
93+
@Input() label: string;
94+
95+
// These were written multiline, so they stay multiline.
96+
@readonly
97+
@nonenumerable
98+
NODE_TYPE: 2;
99+
}
100+
```
101+
102+
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.
103+
104+
<!-- prettier-ignore -->
105+
```js
106+
// Before running Prettier:
107+
@observer class OrderLine {
108+
@observable price: number = 0;
109+
}
110+
```
111+
112+
```js
113+
// After running Prettier:
114+
@observer
115+
class OrderLine {
116+
@observable price: number = 0;
117+
}
118+
```
119+
120+
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:
121+
122+
```js
123+
@observer
124+
class OrderLine {
125+
@observable price: number = 0;
126+
@observable
127+
amount: number = 0;
128+
}
129+
```
130+
131+
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:
132+
133+
```js
134+
@decorator
135+
export class Foo { }
136+
137+
export @decorator class Foo { }
138+
```
139+
38140
### Semicolons
39141

40142
This is about using the [`--no-semi`](options.md#semicolons) option.

0 commit comments

Comments
 (0)