Browse Source

doc: improve formatting of STYLE_GUIDE.md

* Wrap text at 80 characters.
* Use periods consistently.

PR-URL: https://github.com/nodejs/node/pull/13135
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Michael Dawson <mhdawson@ibm.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
v6.x
Alexey Orlenko 8 years ago
committed by Myles Borins
parent
commit
079b04e58d
No known key found for this signature in database GPG Key ID: 933B01F40B5CA946
  1. 21
      doc/STYLE_GUIDE.md

21
doc/STYLE_GUIDE.md

@ -1,16 +1,17 @@
# Style Guide # Style Guide
* Documents are written in markdown files. * Documents are written in markdown files.
* Those files should be written in **`lowercase-with-dashes.md`.** * Those files should be written in **`lowercase-with-dashes.md`**.
* Underscores in filenames are allowed only when they are present in the * Underscores in filenames are allowed only when they are present in the
topic the document will describe (e.g., `child_process`.) topic the document will describe (e.g., `child_process`).
* Filenames should be **lowercase**. * Filenames should be **lowercase**.
* Some files, such as top-level markdown files, are exceptions. * Some files, such as top-level markdown files, are exceptions.
* Older files may use the `.markdown` extension. These may be ported to `.md` * Older files may use the `.markdown` extension. These may be ported to `.md`
at will. **Prefer `.md` for all new documents.** at will. **Prefer `.md` for all new documents.**
* Documents should be word-wrapped at 80 characters. * Documents should be word-wrapped at 80 characters.
* The formatting described in `.editorconfig` is preferred. * The formatting described in `.editorconfig` is preferred.
* A [plugin][] is available for some editors to automatically apply these rules. * A [plugin][] is available for some editors to automatically apply these
rules.
* Mechanical issues, like spelling and grammar, should be identified by tools, * Mechanical issues, like spelling and grammar, should be identified by tools,
insofar as is possible. If not caught by a tool, they should be pointed out by insofar as is possible. If not caught by a tool, they should be pointed out by
human reviewers. human reviewers.
@ -18,12 +19,12 @@
"color" vs. "colour", etc. "color" vs. "colour", etc.
* Though controversial, the [Oxford comma][] is preferred for clarity's sake. * Though controversial, the [Oxford comma][] is preferred for clarity's sake.
* Generally avoid personal pronouns in reference documentation ("I", "you", * Generally avoid personal pronouns in reference documentation ("I", "you",
"we".) "we").
* Pronouns are acceptable in more colloquial documentation, like guides. * Pronouns are acceptable in more colloquial documentation, like guides.
* Use **gender-neutral pronouns** and **mass nouns**. Non-comprehensive * Use **gender-neutral pronouns** and **mass nouns**. Non-comprehensive
examples: examples:
* **OK**: "they", "their", "them", "folks", "people", "developers", "cats" * **OK**: "they", "their", "them", "folks", "people", "developers", "cats"
* **NOT OK**: "his", "hers", "him", "her", "guys", "dudes". * **NOT OK**: "his", "hers", "him", "her", "guys", "dudes"
* When combining wrapping elements (parentheses and quotes), terminal * When combining wrapping elements (parentheses and quotes), terminal
punctuation should be placed: punctuation should be placed:
* Inside the wrapping element if the wrapping element contains a complete * Inside the wrapping element if the wrapping element contains a complete
@ -54,10 +55,12 @@
your point, not as complete running programs. If a complete running program your point, not as complete running programs. If a complete running program
is necessary, include it as an asset in `assets/code-examples` and link to is necessary, include it as an asset in `assets/code-examples` and link to
it. it.
* When using underscores, asterisks and backticks please use proper escaping (**\\\_**, **\\\*** and **\\\`** instead of **\_**, **\*** and **\`**) * When using underscores, asterisks, and backticks, please use proper escaping
* References to constructor functions should use PascalCase (**\\\_**, **\\\*** and **\\\`** instead of **\_**, **\*** and **\`**).
* References to constructor instances should be camelCased * References to constructor functions should use PascalCase.
* References to methods should be used with parentheses: `socket.end()` instead of `socket.end` * References to constructor instances should use camelCase.
* References to methods should be used with parentheses: for example,
`socket.end()` instead of `socket.end`.
[plugin]: http://editorconfig.org/#download [plugin]: http://editorconfig.org/#download
[Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma [Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma

Loading…
Cancel
Save