Skip to content

Latest commit

 

History

History
70 lines (66 loc) · 3.7 KB

STYLE_GUIDE.md

File metadata and controls

70 lines (66 loc) · 3.7 KB
Raw

Style Guide

  • Documentation is in markdown files with names formatted as lowercase-with-dashes.md.

    • Use an underscore in the filename only if the underscore is part of the topic name (e.g., child_process).
    • Some files, such as top-level markdown files, are exceptions.

  • Documents should be word-wrapped at 80 characters.

  • .editorconfig describes the preferred formatting.

    • A plugin is available for some editors to apply these rules.

  • Check changes to documentation with make lint-md.

  • Use American English spelling.

    • OK: capitalize, color
    • NOT OK: capitalise, colour

  • Use serial commas.

  • Avoid personal pronouns (I, you, we) in reference documentation.

    • Personal pronouns are acceptable in colloquial documentation such as guides.
    • Use gender-neutral pronouns and gender-neutral plural nouns.
      • OK: they, their, them, folks, people, developers
      • NOT OK: his, hers, him, her, guys, dudes

  • When combining wrapping elements (parentheses and quotes), place terminal punctuation:

    • Inside the wrapping element if the wrapping element contains a complete clause.
    • Outside of the wrapping element if the wrapping element contains only a fragment of a clause.

  • Documents must start with a level-one heading.

  • Prefer affixing links to inlining links — prefer [a link][] to [a link](http://example.com).

  • When documenting APIs, update the YAML comment associated with the API as appropriate. This is especially true when introducing or deprecating an API.

  • Use Em dashes ("—" or Option+Shift+"-" on macOS) surrounded by spaces, as per The New York Times Manual of Style and Usage.

  • For code blocks:

    • Use language aware fences. ("```js")
    • Code need not be complete. Treat code blocks as an illustration or aid to 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 it.

  • When using underscores, asterisks, and backticks, please use backslash-escaping: \_, \*, and \` .

  • Constructors should use PascalCase.

  • Instances should use camelCase.

  • Denote methods with parentheses: socket.end() instead of socket.end.

  • Function arguments or object properties should use the following format:

    • * `name` {type|type2} Optional description. **Default:** `value`.
    • For example: * byteOffset {integer} Index of first byte to expose. Default: 0.

  • Function returns should use the following format:

    • * Returns: {type|type2} Optional description.
    • E.g. * Returns: {AsyncHook} A reference to asyncHook.

  • Use official styling for capitalization in products and projects.

    • OK: JavaScript, Google's V8
    • NOT OK: Javascript, Google's v8

  • Use Node.js and not Node, NodeJS, or similar variants.

    • When referring to the executable, node is acceptable.

See also API documentation structure overview in doctools README.