Code in text

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.
Data types.
Defined (constant) values for an element or attribute.
DNS record types.
Enum (enumerator) names.
Environment variable names.
Element names (XML and HTML). Place angle brackets (<>) around the element name; you may have to escape the angle brackets to make them appear in the document.
Filenames, filename extensions (if used), and paths.
HTTP verbs.
HTTP status codes.
HTTP content-type values.
Language keywords.
Method and function names.
Namespace aliases.
Placeholder variables.
Query parameter names and values.
Text input.

Generally, don't put quotation marks around code unless the quotation marks are part of the code. When text that precedes a colon is tagged as <code>, such as in a run-in heading that is followed by a colon, don't include the colon in the <code> tagging unless the colon is part of the code. See also Bold text preceding colon.

Items to put in ordinary (non-code) font

The following list includes items that should not be in code font, but it's not an exhaustive list.

Email addresses.
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:

Recommended:
- Invoke the GCC 8.3 compiler using gcc for C programs or g++ for C++ programs.
- To send the file over FTP with IPv6, use ftp -6.
- The options for the curl command are explained on the curl project website.
URLs. But often it's a good idea to put URLs on a separate line, enclosed in a <pre> element, which renders them in code font, or else to turn them into links. For more information, see link text.

Method names

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 animal.get() method.

Recommended: To retrieve the zebra's metadata, call its get() method.

Put an empty pair of parentheses after a method name to indicate that it's a method.

Formatting a command

To mark a block of code such as a lengthy command or a code sample, use the following formatting:

In HTML, use the <pre> element.
In Markdown, use a code fence (```).

Formatting a command with multiple elements:

When a line exceeds 80 characters, you can safely add a line break before some characters, such as a single hyphen, double hyphen, underscore, or quotation marks. Add four spaces to vertically align each line that follows a line break.
When you split a command line with a line break, each line except the last line must end with the command-continuation character. Commands that don't have the command-continuation character don't work.
- Linux or Cloud Shell: A backslash typically preceded with a space ( \)
- Windows: A caret preceded with a space ( ^)
Format placeholder text with placeholder variables.
Follow the command line with a descriptive list of the placeholder variables used in the command line. For more information, see Explaining placeholders.

Placeholder variables

To format a placeholder variable, do the following:

For inline placeholder variables:
- In HTML, wrap placeholders in <code><var> elements, like this:
```
<code><var>PLACEHOLDER_VARIABLE</var></code>
```
- In Markdown, wrap inline placeholders in backticks (`), and use an asterisk (*) before the first backtick and after the second one (*`PLACEHOLDER_VARIABLE`*).
For placeholder variables in code blocks:
- In HTML, wrap the code block in a <pre> element, and tag placeholders with <var> elements.
- In Markdown, wrap the code block in a code fence (```). Inside a code fence, you can't apply formatting like bold or italic.
```
```
  PLACEHOLDER_VARIABLE
```
```
Use uppercase characters with underscore delimiters.

For example, in HTML:

Not recommended:
- https://developers.google.com/<var>API-name</var>
- https://developers.google.com/<var>API_name</var>
- https://developers.google.com/<var>API name</var>
- https://developers.google.com/<var>api_name</var>
- https://developers.google.com/<var>api-name</var>
- https://developers.google.com/<var>apiName</var>
Recommended:
- https://developers.google.com/<var>API_NAME</var>
- https://developers.google.com/<var>METHOD_NAME</var>
And in Markdown:

Recommended:
- https://developers.google.com/*API_NAME*
- https://developers.google.com/*METHOD_NAME*
If the context in which your placeholder variables appear makes using uppercase characters with underscore delimiters a bad idea, use something else that makes sense to you, but be internally consistent.

Don't include possessive pronouns in placeholders.

Not recommended:

https://developers.google.com/<var>MY_API_NAME</var>
https://developers.google.com/<var>YOUR_API_NAME</var>

Note: You can mark up command-line syntax with brackets, braces, and ellipses. Don't put the brackets, braces, or ellipses in the <var> element.

Explaining placeholders

When you use a placeholder in text or code, include an explanation for the placeholder the first time you use it. If there are many steps and other placeholders after the first use of that placeholder, it's OK to explain it again.

In procedures, use the following order:

Tell the user what they're doing.
List the command.
Explain the placeholder.
Explain the command in more detail if necessary.
List any output if necessary.
Explain any output if necessary.

For example:

<pre class="devsite-click-to-copy">
gcloud compute instances create <var>INSTANCE_NAME</var> \
    --metadata enable-guest-attributes=TRUE
</pre>

<p>Replace the following:</p>

<ul>
  <li><code><var>INSTANCE_NAME</var></code>: the
name you want your new VM instance to have</li>
</ul>

Single placeholder

Use the following format for a single placeholder:

Replace PLACEHOLDER with a description of what the placeholder represents.

Recommended:

Stream the build logs to the Google Cloud Console:
```
gcloud builds log --stream=BUILD_ID
```
Replace BUILD_ID with the ID of the WORKING build that you copied in the preceding step. The log stream terminates upon build completion. Messages are displayed that indicate that the final terraform-destroy build step is successful and that the build is done.

Two or more placeholders

Use the following format for two or more placeholders:

Follow the command line with a descriptive list of the placeholder variables used in the command line. Explain what each placeholder represents even if the placeholder value is intuitive to you.
Introduce this list with Replace the following:
List the placeholders in the order in which they appear in the command line.
Provide a description for each placeholder.
Tag each placeholder with <code><var> elements, followed by a colon, for example:
```
<li><code><var>INSTANCE_NAME</var></code>: description</li>
```

Recommended:

In Cloud Shell, set the environment variables:
```
export ONPREM_PROJECT=ON_PREM_PROJECT_NAME
    export ONPREM_ZONE=ZONE
```
Replace the following:
- ON_PREM_PROJECT_NAME: the Google Cloud project name for your on-premises project
- ZONE: a Google Cloud zone that's close to your location
When you end the Cloud Shell session, you lose these environment variables.

Placeholders in output

If you provide an output example, explain any placeholders that appear in sample output.

Use <var> elements to identify the placeholder text in the output.
Follow the example output with a list of the placeholders used in the example.
Introduce the list of placeholders with In this output:
List the placeholders in the order in which they appear in the example.
Provide a description for each placeholder.
Tag each placeholder with <code><var> elements, followed by a colon, for example:
```
<li><code><var>INSTANCE_NAME</var></code>: description</li>
```

Response

The following sample response resembles the output that is returned:

{
 "name": "operations/build/PROJECT_ID/OPERATION_ID",
 "metadata": {
  "@type": "type.googleapis.com/google.devtools.cloudbuild.v1.BuildOperationMetadata",
  "build": {
   "id": "BUILD_ID",
   "status": "QUEUED",
   "createTime": "2019-09-20T15:55:29.353258929Z",
   "steps": [
    {
     "name": "gcr.io/compute-image-tools/gce_vm_image_import:release",
     "env": [
      "BUILD_ID=BUILD_ID"
     ],
     "args": [
      "-timeout=7056s",
      "-image_name=IMAGE_NAME",
      "-client_id=api",
      "-data-disk",
      "-source_file=SOURCE_FILE"
     ]
    }
   ],
   "timeout": "7200s",
   "projectId": "PROJECT_ID",
   "logsBucket": "gs://PROJECT_NUMBER.cloudbuild-logs.googleusercontent.com",
   "options": {
    "logging": "LEGACY"
   },
   "logUrl": "https://console.cloud.google.com/gcr/builds/BUILD_ID?project=PROJECT_NUMBER"
  }
 }
}

In this output:

PROJECT_ID: the project ID for the project that the image was imported into
OPERATION_ID: the ID of the import operation
BUILD_ID: the ID of the build for the import operation
IMAGE_NAME: the name of the image to be imported
SOURCE_FILE: the URI for the image in Cloud Storage, for example, gs://my-bucket/my-image.vmdk
PROJECT_NUMBER: the number for the import project

HTTP status codes

To refer to a single status code, use the following formatting and phrasing:

an HTTP 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:

an HTTP 2xx or 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 200-299 range

Here, too, put the numbers in code font.

Coding style guides

The following Google coding-style guides are available on GitHub:

Keywords

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.

Examples

Not recommended: POST the data.

Recommended: To add the data, send a POST request.

Not recommended: Retrieve information by GETting the data.

Recommended: To retrieve the data, send a GET request.

Not recommended: Close()ing 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 open().

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 INT64 values) and returns BYTES values.

Also recommended: For STRING 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: store the 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 FooFactory instances.

Linking API terms in Android

When you're writing code comments that you'll turn into generated reference documentation, link to all elements of Android APIs, such as classes, methods, constants, and XML attributes. Use code font and regular HTML <a> elements to link to this reference material.

Link AndroidManifest.xml elements and attributes to the API guide pages. Link the attribute for a particular widget or layout to its Javadoc in the widget or layout's API reference entry.

Recommended: <a href="/guide/topics/manifest/data-element.html">data</a>

Very common classes such as Activity and Intent don't need to be linked every time. If you use a term as a concept rather than a class, then don't put it in code font and don't capitalize. Here are some objects that do not always require Javadoc links or capitalization:

activity, activities
service
fragment
view
loader
action bar
intent
content provider
broadcast receiver
app widget

If you use one of these terms in the context of referring to an actual instance, use the formal class name and link to its reference page. Here are two examples:

Recommended: An Activity is an app component that provides a screen with which users can interact...

Recommended: The user interface for an activity is provided by a hierarchy of views—objects derived from the View class.

To link to a class or method:

To link to a class, use the class name as link text. For example:

<a href="/reference/android/widget/TextView">TextView</a>
To link to a method, use the method name as a fragment identifier. If you're linking to a static method, also include the class name in the link text. If you need to distinguish between overloaded versions of a particular method, consider showing the full signature. For example:
```
<a href="/reference/android/app/Activity.html#onCreate(android.os.Bundle)">onCreate(Bundle)</a>
```
To link the attribute for a particular widget or layout to its Javadoc in the widget or layout's API reference entry, use the URL for the page, and then add the fragment identifier #attr_android:attribute_name. For example, to link to the XML attribute android:inputType for the TextView widget, add the following:
```
<a href="/reference/android/widget/TextView.html#attr_android:inputType>inputType</a>
```