Update rationale (#5136)
* Clarify semicolon example * Add rationale for print width Fixes #5081. * Link options and rationale * Add rationale for comments Refs. #5121. * Mention that spaces can be used for alignment for --use-tabs Refs. #4199. * Add missing word * Remove bad `istanbul ignore next` examplemaster
Simon Lydell
GitHub
parent
265d9337f6
commit
a459743eb2
|
|
@ -14,6 +14,8 @@ Specify the line length that the printer will wrap on.
|
|||
> In code styleguides, maximum line length rules are often set to 100 or 120. However, when humans write code, they don't strive to reach the maximum number of columns on every line. Developers often use whitespace to break up long lines for readability. In practice, the average line length often ends up well below the maximum.
|
||||
>
|
||||
> Prettier, on the other hand, strives to fit the most code into every line. With the print width set to 120, prettier may produce overly compact, or otherwise undesirable code.
|
||||
>
|
||||
> See the [print width rationale](rationale.md#print-width) for more information.
|
||||
|
||||
| Default | CLI Override | API Override |
|
||||
| ------- | --------------------- | ------------------- |
|
||||
|
|
@ -31,12 +33,14 @@ Specify the number of spaces per indentation-level.
|
|||
|
||||
## Tabs
|
||||
|
||||
Indent lines with tabs instead of spaces
|
||||
Indent lines with tabs instead of spaces.
|
||||
|
||||
| Default | CLI Override | API Override |
|
||||
| ------- | ------------ | ----------------- |
|
||||
| `false` | `--use-tabs` | `useTabs: <bool>` |
|
||||
|
||||
(Tabs will be used for _indentation_ but Prettier uses spaces to _align_ things, such as in ternaries.)
|
||||
|
||||
## Semicolons
|
||||
|
||||
Print semicolons at the ends of statements.
|
||||
|
|
@ -44,7 +48,7 @@ Print semicolons at the ends of statements.
|
|||
Valid options:
|
||||
|
||||
- `true` - Add a semicolon at the end of every statement.
|
||||
- `false` - Only add semicolons at the beginning of lines that may introduce ASI failures.
|
||||
- `false` - Only add semicolons at the beginning of lines that [may introduce ASI failures](rationale.md#semicolons).
|
||||
|
||||
| Default | CLI Override | API Override |
|
||||
| ------- | ------------ | -------------- |
|
||||
|
|
@ -59,6 +63,8 @@ Notes:
|
|||
- Quotes in JSX will always be double and ignore this setting.
|
||||
- If the number of quotes outweighs the other quote, the quote which is less used will be used to format the string - Example: `"I'm double quoted"` results in `"I'm double quoted"` and `"This \"example\" is single quoted"` results in `'This "example" is single quoted'`.
|
||||
|
||||
See the [strings rationale](#rationale.md#strings) for more information.
|
||||
|
||||
| Default | CLI Override | API Override |
|
||||
| ------- | ---------------- | --------------------- |
|
||||
| `false` | `--single-quote` | `singleQuote: <bool>` |
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ The first requirement of Prettier is to output valid code that has the exact sam
|
|||
|
||||
### Strings
|
||||
|
||||
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 [singleQuote](options.html#quotes) option).
|
||||
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.
|
||||
|
||||
|
|
@ -37,7 +37,7 @@ By default, Prettier’s printing algorithm prints expressions on a single line
|
|||
|
||||
### Semicolons
|
||||
|
||||
This is about using the `--no-semi` option.
|
||||
This is about using the [`--no-semi`](options.md#semicolons) option.
|
||||
|
||||
Consider this piece of code:
|
||||
|
||||
|
|
@ -57,7 +57,7 @@ if (shouldAddLines) {
|
|||
}
|
||||
```
|
||||
|
||||
This is to help you avoid mistakes. Imagine adding this line:
|
||||
This is to help you avoid mistakes. Imagine Prettier _not_ inserting that semicolon and adding this line:
|
||||
|
||||
```diff
|
||||
if (shouldAddLines) {
|
||||
|
|
@ -81,7 +81,15 @@ This practice is also common in [standard] which uses a semicolon-free style.
|
|||
|
||||
[standard]: https://standardjs.com/rules.html#semicolons
|
||||
|
||||
### Imports
|
||||
### Print width
|
||||
|
||||
The [`--print-width`](options.md#print-width) is more of a guideline to Prettier than a hard rule. It generally means “try to make lines this long, go shorter if needed and longer in special cases.”
|
||||
|
||||
There are some edge cases, such as really long string literals, regexps, comments and variable names, which cannot be broken across lines (without using code transforms which [Prettier doesn’t do](#what-prettier-is-not-concerned-about)). Or if you nest your code 50 levels deep your lines are of course going to be mostly indentation :)
|
||||
|
||||
Apart from that, there are a few cases where Prettier intentionally exceeds the print width.
|
||||
|
||||
#### Imports
|
||||
|
||||
Prettier can break long `import` statements across several lines:
|
||||
|
||||
|
|
@ -100,6 +108,20 @@ import { CollectionDashboard } from "../components/collections/collection-dashbo
|
|||
|
||||
This might be unexpected by some, but we do it this way since it was a common request to keep `import`s with single elements in a single line. The same applies for `require` calls.
|
||||
|
||||
#### Testing functions
|
||||
|
||||
Another common request was to keep lengthy test descriptions in one line, even if it gets too long. In such cases, wrapping the arguments to new lines doesn’t help much.
|
||||
|
||||
```js
|
||||
describe("NodeRegistry", () => {
|
||||
it("makes no request if there are no nodes to prefetch, even if the cache is stale", async () => {
|
||||
// The above line exceeds the print width but stayed on one line anyway.
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
Prettier special cases common test framework functions such as `describe`, `it` and `test`.
|
||||
|
||||
### JSX
|
||||
|
||||
Prettier prints things a little differently compared to other JS when JSX is involved:
|
||||
|
|
@ -136,6 +158,47 @@ Secondly, [the alternate formatting makes it easier to edit the JSX](https://git
|
|||
</div>
|
||||
```
|
||||
|
||||
### Comments
|
||||
|
||||
When it comes to the _contents_ of comments, Prettier can’t do much really. Comments can contain everything from prose to commented out code and ASCII diagrams. Since they can contain anything, Prettier can’t know how to format or wrap them. So they are left as-is. The only exception to this are JSDoc-style comments (block comments where every line starts with a `*`), which Prettier can fix the indentation of.
|
||||
|
||||
Then there’s the question of _where_ to put the comments. Turns out this is a really difficult problem. Prettier tries it best to keep your comments roughly where they where, but it’s no easy task because comments can be placed almost anywhere.
|
||||
|
||||
Generally, you get the best results when placing comments **on their own lines,** instead of at the end of lines. Prefer `// eslint-disable-next-line` over `// eslint-disable-line`.
|
||||
|
||||
Note that “magic comments” such as `eslint-disable-next-line` and `$FlowFixMe` might sometimes need to be manually moved due to Prettier breaking an expression into multiple lines.
|
||||
|
||||
Imagine this piece of code:
|
||||
|
||||
```js
|
||||
// eslint-disable-next-line no-eval
|
||||
const result = safeToEval ? eval(input) : fallback(input);
|
||||
```
|
||||
|
||||
Then you need to add another condition:
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
```js
|
||||
// eslint-disable-next-line no-eval
|
||||
const result = safeToEval && settings.allowNativeEval ? eval(input) : fallback(input);
|
||||
```
|
||||
|
||||
Prettier will turn the above into:
|
||||
|
||||
```js
|
||||
// eslint-disable-next-line no-eval
|
||||
const result =
|
||||
safeToEval && settings.allowNativeEval ? eval(input) : fallback(input);
|
||||
```
|
||||
|
||||
Which means that the `eslint-disable` comment is no longer effective. In this case you need to move the comment:
|
||||
|
||||
```js
|
||||
const result =
|
||||
// eslint-disable-next-line no-eval
|
||||
safeToEval && settings.allowNativeEval ? eval(input) : fallback(input);
|
||||
```
|
||||
|
||||
## What Prettier is _not_ concerned about
|
||||
|
||||
Prettier only _prints_ code. It does not transform it. This is to limit the scope of Prettier. Let's focus on the printing and do it really well!
|
||||
|
|
@ -143,6 +206,7 @@ Prettier only _prints_ code. It does not transform it. This is to limit the scop
|
|||
Here are a few examples of things that are out of scope for Prettier:
|
||||
|
||||
- Turning single- or double-quoted strings into template literals or vice versa.
|
||||
- Using `+` to break long string literals into parts that fit the print width.
|
||||
- Adding/removing `{}` and `return` where they are optional.
|
||||
- Turning `?:` into `if`-`else` statements.
|
||||
- Sorting and hoisting `import`s. (Sorting is unsafe because of side effects, which would violate the [correctness](#correctness) goal.)
|
||||
|
|
|
|||
Loading…
Reference in New Issue