Code samples

A code sample is often the first thing a developer reads on a page, and the part they copy. These rules cover the sample block itself: how to introduce it, how to format it, and how to keep it runnable as copied. Code elements inside sentences and placeholder values have their own pages.

Introduce every sample

code-003 should GuidesAPI docs

Precede every code sample with an introductory sentence or paragraph that explains what the sample demonstrates and lists any requirements or dependencies.

Examples

• ✓ The following example authenticates with an API key and lists your projects. It requires version 2.0 or later of the SDK:
• ✗ Example:

Rationale

An introduction tells the reader what the sample shows and what it needs before they read the code.

Colon or period before a sample

code-004 should GuidesAPI docs

End the introductory statement with a colon when it immediately precedes the code sample, and with a period when intervening material (such as a note) separates the introduction from the sample.

Examples

• ✓ To create the bucket, run the following command:
• ✗ To create the bucket, run the following command.
• ✓ The following sample streams the response. (a note separates this sentence from the sample, so it ends with a period)

Start simple, build up

code-010 should GuidesAPI docs

Code samples should be concise, start with simple cases, and build toward complexity; reserve complex multi-feature examples for tutorials with step-by-step explanations.

Rationale

Starting simple lets a reader grasp the basic case before complexity is layered on.

Keep samples runnable as copied

code-011 should GuidesAPI docs

Provide a way for developers to copy and run code examples directly; design click-to-copy examples to be runnable without editing (avoid optional-argument syntax characters in click-to-copy blocks).

Examples

• ✓ tool deploy APP_NAME —region=REGION
• ✗ tool deploy APP_NAME [—region=REGION]

Rationale

A sample a developer can copy and run without editing removes a step and a source of error.

Line length

code-005 should GuidesAPI docsMarketingBlog

Aim for code sample lines under 80 characters so samples render cleanly on mobile viewports, in side-by-side layouts, and in PDF exports. Wider lines are acceptable for long URLs, string literals, error messages, and structured formats such as JSON and YAML.

Examples

• ✓ client.jobs.create(name="nightly-export", retries=3) — 52 characters, renders cleanly everywhere
• ✗ A 140-character line chaining client.jobs.create(...).wait().download().save(...) that scrolls horizontally on mobile

Rationale

Lines under about 80 characters render cleanly on mobile, in side-by-side views, and in PDF, so it is a useful soft target. Long URLs, strings, and structured formats are reasonable exceptions where wrapping would hurt readability.

Mark code as preformatted

code-007 should GuidesAPI docs

Mark code blocks as preformatted text using the appropriate mechanism for the authoring format: the pre element in HTML, a code fence or four-space indent in Markdown.

Examples

• ✓ <pre><code>npm install example-sdk</code></pre>
• ✗ <p>npm install example-sdk</p>

Rationale

Marking code as preformatted preserves whitespace and stops the renderer from reflowing it.

Indentation

code-006 should GuidesAPI docs

Follow the relevant language style guide for indentation; prefer spaces over tabs and use two spaces per indentation level unless the language convention differs.

Examples

• ✓ A JavaScript sample indented two spaces per level
• ✗ A JavaScript sample indented four spaces per level, against the language convention

Rationale

Following the language’s own conventions keeps samples idiomatic and ready to copy.

HTML indentation

code-002 should GuidesAPI docs

Indent HTML source with two spaces per level; do not use tabs.

Examples

• ✓ <li> items indented two spaces inside their <ul>
• ✗ <li> items indented with tab characters

HTML line length

code-001 should GuidesAPI docs

Limit HTML source line length to 80 characters, with defined exceptions for meta elements and long URLs.

Examples

• ✓ An <a> tag wrapped after its class attribute so no source line passes 80 characters
• ✗ <a class="btn btn-primary" href="https://example.com/docs/get-started" title="Get started with the API">Get started</a>

Rationale

Constrained line length keeps HTML source readable and diff-friendly.

Mark omitted code with a comment

code-008 should GuidesAPI docs

Indicate omitted code within a sample using a comment in the language’s own syntax rather than ellipsis characters or three dots.

Examples

• ✓ // Omitted: client setup shown in the previous sample
• ✗ …

Rationale

A language comment for elided code stays valid in the sample, while bare ellipses can look like syntax.

Match the language’s capitalization

code-012 should GuidesAPI docs

Capitalize code elements according to the conventions of the programming language or API being documented.

Examples

• ✓ Call getElementById() to find the element. (JavaScript)
• ✗ Call GetElementByID() to find the element.

Rationale

Matching the language’s casing keeps samples correct and runnable.

Don’t inflect code element names

code-009 should GuidesAPI docs

Do not inflect code element names to form plurals or possessives; instead, add a noun after the element name and inflect that noun (‘Intent objects’, not ‘Intents’).

Examples

• ✓ Delete the unused Intent objects.
• ✗ Delete the unused Intents.

Rationale

Adding an English plural to a code name creates a token that is not the real identifier; a following noun keeps the name exact.