Code Examples

To learn more about the types of code examples used in our docs, see Code Example Guidelines.

General Formatting Guidelines

Use the following markup and formatting guidelines when creating code examples. For more information on code example directives and their markup, see Code Examples.

Always format code examples as blocks of code using either literalinclude or io-code-blocks directives that point directly to the actual code file.
- Don't hard-code a code-block directly on the page, or manually format a code example using monospace.
- For code examples where a return is expected or the output is otherwise relevant to users, use the .. io-code-block:: directive to show both the input and output code files.
Don't use screenshots to show code examples.
Don't nest code in other components. To learn more, see Nested Components Guidelines.

Code Directive Options

For large code examples, use :emphasize-lines: to highlight the sections most relevant to the user.
Always specify the code language, including output examples in an io-code-block.
Code block directives are always copyable by default. Set copyable to false for code examples that are not intended to be copied by users, such as example return objects or syntax examples.
The output in an io-code-block is always visible by default. Set visible to false for large output files.
Don't include linenos in code examples unless needed for the task or example type.
For tasks that reference multiple code examples as files, use the caption option to specify which file the example is referring to.
```
.. literalinclude:: /path/to/code/file/index.js
   :caption: index.js
   :category: usage example
```

General Style Guidelines

Use the following style guidelines when creating code examples:

Introduce each code block with context, as you would a list or table.
Use an ellipsis (...) to denote where code has been deliberately omitted or truncated in an example.
```
[
   {
      "key": "value"
      "anotherKey": "value"
      ...
   }
]
```
Include comments to explain anything that isn't self-evident from the code, such as non-obvious logic, behavior, or intent, or to provide any additional context needed to understand the example. Don't restate the code.
Follow the conventions of the programming language used and preserve the capitalization that the author of the code used.
Use consistent, descriptive names that clearly convey the purpose of the code element (e.g. variable, function, class) or placeholder. Avoid vague names like foo, x, or doStuff().
Prefer conventional file structures, names, and canonical patterns (for example, main(), index.js, connect()) that users expect.
Don't use real data.
Important
Never Hard-Code Secrets
Never include real passwords, secrets, or other sensitive information in a code example. If you're unsure how to handle credentials in your code, reach out to the @DevDocs team or use the #ask-devdocs Slack channel.
Ensure that any placeholder text in code is obvious. Format placeholders as directed in API Placeholders.

Shell Commands

For shell commands, use the following guidelines when creating blocks of code as input or output examples:

When showing input, do not include a command prompt (such as $).
As often as necessary, show input and output in separate blocks and provide explanations for each. For example, if the input contains arguments or parameters, explain those. If the user should expect something specific in the output, or you want to show only part of lengthy output, provide an explanation.
When the command is simple, and there's nothing specific to say about the output, you can show the input and output using the .. io-code-block:: directive.
For readability, you can break up long lines of shell input into readable blocks by ending each line with a backslash (`\).
If the input includes a list of arguments or parameters, show the important or relevant ones first, and group related ones. If no other order makes sense, use alphabetical order. If you explain the arguments or parameters in text, show them in the same order that they appear in the code block.
Use placeholder and variable text as directed in Placeholder or Variable Text.

Back

Citations

Contractions

General Formatting Guidelines

Code Directive Options

General Style Guidelines

Important

Never Hard-Code Secrets

Shell Commands