In ordinary text sentences (as opposed to, say, code samples), use code font to mark up most
things that have anything to do with code. In HTML, use the
<code> element; in Markdown, use backticks
Some specific items to put in code font
The following list includes items that should be in code font, but it's not an exhaustive list.
- Attribute names and values.
- Class names.
- Command-line utility names.
- Defined (constant) values for an element or attribute.
- Environment variable names.
- Data types.
- XML and HTML element names. (Also place angle brackets
<>) around the element name; you may have to escape the angle brackets to make them appear in the document.)
- Filenames and paths.
- HTTP verbs.
- HTTP status codes.
- HTTP content-type values.
- Language keywords.
- Method and function names.
- Namespace aliases.
- Query parameter names and values.
- DNS record types.
Generally don't put quotation marks around an item that's in code font, unless the quotation marks are part of the item.
Items to put in ordinary (non-code) font
- URLs. (But often it's a good idea to put these on a separate line,
<pre>, or else to turn them into links. See also the page on link text.)
- Email addresses.
- Headings (including table headings). For clarity, where possible, add a noun to the code-related term in the heading: "Calling the Foo method"; "Setting the Bar parameter".
- Names of products, services, and organizations.
Often, command-line utility names are spelled the same as the software project or product with which they are associated, with only differences in capitalization. In such cases, use code font for the command and ordinary font for the name of the project or product. For example:
- Invoke the GCC 8.3 compiler using
gccfor C programs or
g++for C++ programs.
- To send the file over FTP with IPv6, use
- The options for the
curlcommand are explained on the curl project website.
Other HTML elements for code
Avoid use of the
<xmp> element; it's deprecated
in modern HTML.
<kbd> element to indicate input to be typed (or
otherwise entered) by the user. Use the
<var> element to
indicate any variable (including both specific variable names from code samples
and metasyntactic placeholder variables like foo). Note that you can
use these elements even within a
<pre> block; for
<pre> $ <kbd>ls <var>filename</var></kbd> <var>filename</var> $ </pre>
When you refer to a method name in text, omit the class name except where including it would prevent ambiguity. For example:
Not recommended: To retrieve the zebra's
metadata, call its
Recommended: To retrieve the zebra's
metadata, call its
Put an empty pair of parentheses after a method name to indicate that it's a method.
To create a placeholder variable, do the following:
- In HTML, wrap the placeholder variable in a
- In Markdown, use an underscore before and after the placeholder variable.
For placeholder variables, use lowercase characters with hyphen delimiters.
For example, in HTML:
- https://developers.google.com/<var>API name</var>
And in Markdown:
- https://developers.google.com/_API name_
If the context in which your placeholder variables appear makes using lowercase characters with hyphen delimiters a bad idea, use something else that makes sense to you, but be internally consistent.
When you use a placeholder in text or code, consider the following:
- Explain what the placeholder represents even if the placeholder value is intuitive to you.
- Include the explanation the first time you use the placeholder. If there are many steps and other placeholders after the first use of that placeholder, it's OK to explain it again.
- In procedural steps, use the following order:
- Tell the user what they're doing.
- List the command.
- Explain the placeholders.
- Explain the command in more detail if necessary.
- Explain any output if necessary.
- Use the following format for the placeholder explanation:
placeholder-variable-1with an explanation of placeholder.
- Stream the build logs to the GCP Console:
gcloud builds log --stream build-idReplace
build-idwith the ID of the
WORKINGbuild that you copied in the preceding step. The log stream terminates upon build completion. Messages are displayed that indicate the final
terraform-destroybuild step is successful and that the build is done.
- Stream the build logs to the GCP Console:
- Use the following format for the placeholder explanation of two or more placeholder
Replace the following:
placeholder-variable-1: Explanation of placeholder.
placeholder-variable-2: Explanation of placeholder.
- In Cloud Shell, set the environment variables:
export ONPREM_PROJECT=your-on-prem-project export ONPREM_ZONE=zoneReplace the following:
your-on-prem-project: The GCP project name for your on-premises project.
zone: A GCP zone that's close to your location.
HTTP status codes
To refer to a single status code, use the following formatting and phrasing:
400 Bad Request status code
In particular, call it a "status code" instead of a "response code," and put the number and the name in code font. If the "HTTP" is implicit from context, you can leave it out.
To refer to a range of codes, use the following form:
400 status code
In particular, use "nxx" (with a specific digit in place of n) to indicate "anything in the n00-n99 range," and put the status code number in code font even if you're leaving out the code's name.
If you prefer to specify an exact range, you can do so:
an HTTP status code in the
Here, too, put the numbers in code font.
Coding style guides
The following Google coding-style guides are available on GitHub:
In general, don't use technical keywords as if they were English verbs or
nouns. If in some rare cases you do, then don't try to inflect them. Don't form
plurals from keywords and don't make keywords possessive. It's okay to use
lowercase, plain text string in a general discussion of the
STRING data type.
Recommended: To add the data, send a
Not recommended: Retrieve information by
GETting the data.
Recommended: To retrieve the data, send a
the file requires you to have
open()ed it first.
Recommended: You can't close the file before opening it.
Also recommended: You can't call the
close() method for a file before you call
Not recommended: Takes an array of extended ASCII code points (ARRAY of INT64) and returns BYTES.
Recommended: Takes an array of
extended ASCII code points (an array of
Also recommended: For
arguments, returns the original string with all alphabetic characters in uppercase.
Exception: When documenting a Java API, it's common to leave out words
like "object" or "instance" and instead just use the class name as a noun:
Foo you got from the
FooFactory." If you
need to pluralize such nouns, then add "object" or "instance": "store the
Foo objects you got from the