Placeholders

Placeholders stand in for values the reader supplies, so they have to be recognizable as not-real code at a glance. These rules cover how to format placeholders in samples and in running text, how to name them, and how to explain what each one stands for.

Code font for developer elements

placeholder-001 should GuidesAPI docsMarketingBlog

Use code font for all developer text elements appearing in body text: attributes, classes, methods, constants, variables, parameters, environment variables, commands, flags, data types, and markup elements. Use italic for placeholders (formatted as UPPERCASE_WITH_UNDERSCORES), mathematical variables, and new terms defined at first mention.

Examples

• ✓ Set the timeout field in the request body.
• ✗ Set the “timeout” field in the request body.
• ✓ A webhook is a URL that the API calls when an event occurs. (new term at first mention)
• ✗ A webhook is a URL that the API calls when an event occurs.

Rationale

Code font is the recognized signal for a code element in body text, so applying it consistently tells the reader what is literal code and reserves italic and bold for their own uses.

Uppercase placeholder format

placeholder-002 should GuidesAPI docsMarketingBlog

Format placeholders in code samples, commands, and syntax descriptions as uppercase with underscores between words: PROJECT_ID, USER_NAME, API_KEY. Placeholders appear in code font; the uppercase pattern provides sufficient visual distinction without italic or other emphasis.

Examples

• ✓ tool config set project PROJECT_ID
• ✗ tool config set project <project-id>

Rationale

Uppercase with underscores marks a value as a placeholder to replace, renders reliably everywhere, stays distinct from real code, and is safe to copy and to check with a linter.

Italicize placeholders in running text

placeholder-006 should GuidesAPI docs

Italicize placeholder names in running text and syntax descriptions; do not use them as ordinary English terms.

Examples

• ✓ Replace PROJECT_ID with the ID of your project.
• ✗ Replace PROJECT_ID with the ID of your project.

Descriptive placeholder names

placeholder-004 should GuidesAPI docs

Use meaningful, descriptive placeholder names; avoid foo, bar, baz, single letters, or series of x’s.

Examples

• ✓ BUCKET_NAME, SERVICE_ACCOUNT_EMAIL
• ✗ FOO, X1

Rationale

A descriptive placeholder name tells the reader what value goes there; foo and x do not.

Consistent placeholder names

placeholder-005 should GuidesAPI docs

Be consistent when naming placeholders throughout a document; do not alternate between different names for the same concept.

Examples

• ✓ API_KEY in every sample in the guide
• ✗ API_KEY in step 1, YOUR_API_KEY in step 3

Rationale

Switching names for the same placeholder makes a reader wonder whether they refer to different things.

Explain every placeholder

placeholder-003 should GuidesAPI docs

Explain every placeholder the first time it appears; for two or more placeholders, follow the code block with a descriptive list in the order the placeholders appear.

Examples

• ✓ After the code block: “Replace PROJECT_ID with your project ID and REGION with the region to deploy to.”
• ✗ Replace the placeholders with your values.

Rationale

A reader has to know what each placeholder stands for to replace it correctly.