# Code and API documentation detail

Detail for: code font usage, code samples, command-line syntax, placeholders,
API reference comments, semantic tagging, HTML/Markdown formatting. Source:
developers.google.com/style (Code in text, Code samples, Code syntax,
Placeholders, API reference comments, Semantic tagging, HTML formatting,
Markdown).

## Code font (inline code)

Put in code font (backticks in Markdown, `code` in HTML) anything the reader
types or that is a code entity. Non-exhaustive list:

| Item | Example |
|---|---|
| Attribute names and values | "the `imageURL` attribute" |
| Class names / method names | "the `SnapshotDiskOperator` class includes the `generate_snapshot_name` method" |
| Command output | "The output is similar to the following: ..." |
| Command-line utility names | "the `gcloud` tool", "the `kubectl` tool" |
| Data types | "Nested data is represented as a `STRUCT` type" |
| Database elements | "the `julianday` and `dayofweek` values from the `datetime` and `timestamp` columns" |
| Element names (HTML/XML) | "the `script` and `df-messenger` HTML elements" (no angle brackets) |
| Enum / constant values | "the constant `city` has the value `"San Francisco"`" |
| Environment variables | "Set the `CHROME_REMOTE_DESKTOP_DEFAULT_DESKTOP_SIZES` environment variable" |
| Filenames, extensions, paths | "the `pg_hba.conf` file, in the `/etc/postgresql/13/main` directory" |
| HTTP verbs / status codes / content types | "send a `POST` request", "the `500 Internal Server Error` status code" |
| IP addresses, machine types, regions (when code-like) | "the `e2-highcpu-16` machine type in the `us-central1-a` region" |
| Boolean values as literals | "If the update succeeds, returns `true`." |
| Literal text the reader types into a field | "In the **Name** field, enter `my-instance-99`" |

Do **not** use code font for: domain names (use example.com), product/service
names, or URLs the reader follows in a browser (make them links with
descriptive text instead).

### Grammatical treatment of code elements

- Never inflect code as English — no pluralizing, possessives, or verbing.
  Include a noun after the code item and inflect that noun:
  - "the value of the `ADDRESS` constant" (not "`ADDRESS`'s value")
  - "send a `POST` request" (not "`POST` the data")
  - "call the `close` method" (not "`Closeing` the file")
- Follow code spelling/capitalization exactly.

## Code samples (blocks)

- Indent with spaces (two per level per Google style; follow the language's
  style guide); wrap lines at ~80 chars.
- Markdown: fenced code blocks with the language for syntax highlighting.
  HTML: `<pre>`.
- Introduce the sample with a sentence; end with a colon if the sample directly
  follows, a period if material intervenes.
- Show omissions with a language-appropriate comment ("... // Existing code").
- Don't rely on code samples alone — explain what the code does when relevant.

## Command-line syntax

- Show the command plus its most common use case. Prefer click-to-copy simple
  commands over exhaustive syntax.
- Optional arguments: document the common options, not every flag. Keep
  mutually exclusive options clear ("`-a` or `-b`, not both").
- Placeholders (see below) for values the reader replaces.
- When showing output, include only the relevant parts and introduce it
  ("The output is similar to the following:").
- Use "run the `gcloud` command", not "gcloud it".

## Placeholders

- Placeholders represent values the reader must replace. Give them descriptive
  names: `PROJECT_ID`, `LOCATION`, `EMAIL_ADDRESS` — not `VALUE1`.
- In inline text and code blocks, format per your project's convention (often
  angle brackets `<PROJECT_ID>` in syntax docs, or italic/capitalized in code
  samples — follow the house convention).
- Explain each placeholder the first time it appears ("Replace `PROJECT_ID`
  with your project's ID.").
- Use placeholder names consistently within a document.

## API reference comments

- Document every public class, constant, method, parameter, and return value.
- First line: a concise statement of purpose in present tense, imperative or
  descriptive ("Creates a new task on the specified task list.").
- Parameter descriptions: purpose and expected values; state behavior for
  booleans and defaults explicitly ("If `true`, validates the certificate.").
- Return value: what information is returned, not a restatement of the method.
- Avoid redundancy with the signature; don't repeat the method name as the
  whole description.
- Deprecations: state the replacement and guidance for updating code.

## Semantic tagging (HTML)

- Use elements for their purpose: `em` = emphasis, `strong` = strong
  importance, `cite` = titles of works, `kbd` = keyboard keys, `pre` =
  preformatted, `b` = attention without importance (used for UI labels).
- Use headings only for hierarchical structure, CSS for visual styling.
- No tables or frames for layout.
- See the HTML formatting rules: two-space indentation, lowercase elements and
  attributes, no trailing spaces, 80-char lines (except URLs and meta lines).

## Markdown vs HTML

- Markdown is preferred for readability; switch to HTML (`code`, `kbd`, spans
  for nonbreaking spaces, etc.) when you need effects Markdown can't express.
- Follow the project's existing convention.
- Don't use tabs for indentation (Markdown features expect spaces); no trailing
  whitespace.