1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
|
# 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.
|
