|
1 | 1 | # Style Guide
|
2 | 2 |
|
3 |
| -* Documentation is written in markdown files with names formatted as |
| 3 | +* Documentation is in markdown files with names formatted as |
4 | 4 | `lowercase-with-dashes.md`.
|
5 |
| - * Underscores in filenames are allowed only when they are present in the |
6 |
| - topic the document will describe (e.g. `child_process`). |
| 5 | + * Use an underscore in the filename only if the underscore is part of the |
| 6 | + topic name (e.g., `child_process`). |
7 | 7 | * Some files, such as top-level markdown files, are exceptions.
|
8 | 8 | * Documents should be word-wrapped at 80 characters.
|
9 |
| -* The formatting described in `.editorconfig` is preferred. |
10 |
| - * A [plugin][] is available for some editors to automatically apply these |
11 |
| - rules. |
12 |
| -* Changes to documentation should be checked with `make lint-md`. |
13 |
| -* American English spelling is preferred. |
| 9 | +* `.editorconfig` describes the preferred formatting. |
| 10 | + * A [plugin][] is available for some editors to apply these rules. |
| 11 | +* Check changes to documentation with `make lint-md`. |
| 12 | +* Use American English spelling. |
14 | 13 | * OK: _capitalize_, _color_
|
15 | 14 | * NOT OK: _capitalise_, _colour_
|
16 | 15 | * Use [serial commas][].
|
|
19 | 18 | * Use gender-neutral pronouns and gender-neutral plural nouns.
|
20 | 19 | * OK: _they_, _their_, _them_, _folks_, _people_, _developers_
|
21 | 20 | * NOT OK: _his_, _hers_, _him_, _her_, _guys_, _dudes_
|
22 |
| -* When combining wrapping elements (parentheses and quotes), terminal |
23 |
| - punctuation should be placed: |
| 21 | +* When combining wrapping elements (parentheses and quotes), place terminal |
| 22 | + punctuation: |
24 | 23 | * Inside the wrapping element if the wrapping element contains a complete
|
25 |
| - clause — a subject, verb, and an object. |
| 24 | + clause. |
26 | 25 | * Outside of the wrapping element if the wrapping element contains only a
|
27 | 26 | fragment of a clause.
|
28 | 27 | * Documents must start with a level-one heading.
|
29 | 28 | * Prefer affixing links to inlining links — prefer `[a link][]` to
|
30 | 29 | `[a link](http://example.com)`.
|
31 |
| -* When documenting APIs, note the version the API was introduced in at |
32 |
| - the end of the section. If an API has been deprecated, also note the first |
33 |
| - version that the API appeared deprecated in. |
34 |
| -* When using dashes, use [Em dashes][] ("—" or `Option+Shift+"-"` on macOS) |
35 |
| - surrounded by spaces, as per [The New York Times Manual of Style and Usage][]. |
36 |
| -* Including assets: |
37 |
| - * If you wish to add an illustration or full program, add it to the |
38 |
| - appropriate sub-directory in the `assets/` dir. |
39 |
| - * Link to it like so: `[Asset](/assets/{subdir}/{filename})` for file-based |
40 |
| - assets, and `` for image-based assets. |
41 |
| - * For illustrations, prefer SVG to other assets. When SVG is not feasible, |
42 |
| - please keep a close eye on the filesize of the asset you're introducing. |
| 30 | +* When documenting APIs, update the YAML comment associated with the API as |
| 31 | + appropriate. This is especially true when introducing or deprecating an API. |
| 32 | +* Use [Em dashes][] ("—" or `Option+Shift+"-"` on macOS) surrounded by spaces, |
| 33 | + as per [The New York Times Manual of Style and Usage][]. |
43 | 34 | * For code blocks:
|
44 | 35 | * Use language aware fences. ("```js")
|
45 |
| - * Code need not be complete — treat code blocks as an illustration or aid to |
| 36 | + * Code need not be complete. Treat code blocks as an illustration or aid to |
46 | 37 | your point, not as complete running programs. If a complete running program
|
47 | 38 | is necessary, include it as an asset in `assets/code-examples` and link to
|
48 | 39 | it.
|
49 |
| -* When using underscores, asterisks, and backticks, please use proper escaping |
50 |
| - (`\_`, `\*` and ``\` `` instead of `_`, `*` and `` ` ``). |
51 |
| -* References to constructor functions should use PascalCase. |
52 |
| -* References to constructor instances should use camelCase. |
53 |
| -* References to methods should be used with parentheses: for example, |
54 |
| - `socket.end()` instead of `socket.end`. |
| 40 | +* When using underscores, asterisks, and backticks, please use |
| 41 | + backslash-escaping: `\_`, `\*`, and ``\` ``. |
| 42 | +* Constructors should use PascalCase. |
| 43 | +* Instances should use camelCase. |
| 44 | +* Denote methods with parentheses: `socket.end()` instead of `socket.end`. |
55 | 45 | * Function arguments or object properties should use the following format:
|
56 | 46 | * ``` * `name` {type|type2} Optional description. **Default:** `value`. ```
|
57 | 47 | <!--lint disable maximum-line-length remark-lint-->
|
|
0 commit comments