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 (
`
).
This page explains how to format code in ordinary text sentences. For more information about formatting placeholders, command-line syntax, and code samples, see the following links:
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.
- Folders and directories.
- 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.
- UI elements that are rendered based on previously entered
text input. For example, if a user was instructed in a procedure to enter an instance name as
my-instance
, when you tell them to click the instance name, use code font and bold: Clickmy-instance
.
Generally, don't put quotation marks around code unless the quotation marks are part of the code.
See also
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.
Recommended:
- Invoke the GCC 8.3 compiler using
gcc
for C programs org++
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.
- Invoke the GCC 8.3 compiler using
- 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.
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. After the first line, indent each line by 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 (
^
)
- Linux or Cloud Shell: A backslash typically 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.
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 or error 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:
- C++ style guide.
- HTML/CSS style guide.
- Java style guide.
- JavaScript style guide.
- Python style guide
- Full list of Google's programming style guides
Some open source projects have their own overriding style guides. For example, Java code in the Android Open Source Project follows the AOSP Java Code Style for Contributors guide.
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
GET
ting 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 MyClass
you got from the
ClassFactory
. If you need to pluralize such nouns, then add
object or instance: store the MyClass
objects you got
from the ClassFactory
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 attributeandroid:inputType
for theTextView
widget, add the following:<a href="/reference/android/widget/TextView.html#attr_android:inputType>inputType</a>