nodejs/doc/STYLE_GUIDE.md

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.
  • The type should refer to a Node.js type or a JavaScript type.

• 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.