# Code and interfaces

From the Google developer documentation style guide; each section names its
source page. The commit-body and code-comment sections at the end are
extensions: the guide covers API reference comments, not ordinary inline
comments or commit messages.

Guide content © Google, used under CC BY 4.0
(https://creativecommons.org/licenses/by/4.0/).

## Contents

- [Code font in text](#code-font-in-text)
- [Code samples](#code-samples)
- [Command-line syntax](#command-line-syntax)
- [Placeholders](#placeholders)
- [Example data](#example-data)
- [UI elements](#ui-elements)
- [API reference comments](#api-reference-comments)
- [Verbs in reference documents](#verbs-in-reference-documents)
- [Commit bodies](#commit-bodies)
- [Inline code comments](#inline-code-comments)

## Code font in text

Source: https://developers.google.com/style/code-in-text

Code font for: attribute names and values, class names, command output,
command-line utilities, data types, column and row names, DNS record types,
element names, environment variables, filenames and paths, HTTP headers, status
codes, HTTP verbs, IAM roles, IP addresses, language keywords, method names,
package names, port numbers, query parameters, and values the user typed.

Plain font for: product and service names, domain names in prose, URLs the
reader opens in a browser, and conceptual mentions of components ("the activity
lifecycle").

Don't inflect a code item as English: "call the `close` method", not
"`close`ing". Don't form its possessive.

## Code samples

Source: https://developers.google.com/style/code-samples

Introduce every sample with a sentence. Colon if the sample follows immediately,
period if anything intervenes:

- "The following code sample shows how to use the `get` method: ..."
- "The following code sample shows how to use the `get` method. For information
  about other methods, see [...]."

Wrap lines at 80 characters. Follow the language's own style guide for
indentation, usually spaces. Mark omitted code with a comment in the language's
syntax, never with an ellipsis. Don't offer a sample containing omissions as
click-to-copy.

## Command-line syntax

Source: https://developers.google.com/style/code-syntax

Start each input line with `$`, with no directory path before it. When the shell
context changes, show it:

```
$ adb shell
shell@ $ screencap /sdcard/screen.png
shell@ $ exit
$ adb pull /sdcard/screen.png
```

A single one-line command can omit the `$` unless it sits beside multi-line
examples.

Break lines over 80 characters before a hyphen, double hyphen, underscore, or
quotation mark; indent continuations four spaces; end each line but the last
with `\` on Linux or `^` on Windows.

Optional arguments in square brackets, mutually exclusive ones in braces with
pipes, repeating ones with `...` and no space: `[ARG]`, `{OPT1|OPT2}`, `ARG...`.
Keep all three out of click-to-copy blocks. Strip the optional parts and link to
the full reference instead.

Show output only when it adds something, introduced with "The output is the
following:" or "The output is similar to the following:". Mark elided output
lines with `...` on its own line.

## Placeholders

Source: https://developers.google.com/style/placeholders

Uppercase with underscores: `API_NAME`, `METHOD_NAME`. Not `api_name`,
`apiName`, or `API-name`. No possessive prefixes: never `MY_API_NAME` or
`YOUR_API_NAME`.

Document one placeholder inline: "Replace `PROJECT_ID` with your project ID." For
several, introduce with "Replace the following:" and give one list item per
placeholder, each description starting lowercase.

## Example data

Source: https://developers.google.com/style/examples

Use reserved values so nothing in an example resolves to something real:

- Domains: example.com, example.org, example.net
- Email: a given name at a reserved domain, such as dana@example.com
- Names: Alex, Amal, Ariel, Bola, Charlie, Cruz, Dana, Hao, Ira, Izumi, Jie, Kai,
  Kalani, Kim, Kiran, Lee, Lucian, Luka, Mahan, Noam, Nur, Quinn, Raha, Rosario,
  Sasha, Tal, Taylor, Tristan, Yuri, Dani. Use an initial for a surname:
  "Quinn N."
- Company: Example Organization
- Phone: 800-555-0100 through 800-555-0199
- IPv4: 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24. IPv6: 2001:db8::/32

Never real or personally identifiable data. Never `foo`, `bar`, or `baz`:
placeholder names should mean something in the reader's own environment, like
`staging` or `production-1`.

## UI elements

Source: https://developers.google.com/style/ui-elements

Bold for the element's label, in the page's own capitalization, converted to
sentence case if the page shouts. Never code font unless the string qualifies on
its own.

Recommended, with the labels capitalized as the page itself capitalizes them:
"In the **New Project** window, select the **New Activity** checkbox, and then
click **Next**."

Don't use an element name as a verb: "In the **Name** field, enter an account
name," not "**Name** the account."

- Checkboxes are *selected* and *cleared*, not checked and unchecked.
- Menus hold *commands*, not options or choices.
- Describe a toggle by its effect: "To turn on the setting, click the **Wi-Fi**
  toggle."
- *in* a dialog, field, list, menu, pane, or window; *on* a page, tab, or
  toolbar.
- Keys: spell out modifiers, uppercase letter keys, join with `+`: Control+C.

Verbs that work: click, choose, drag, enable, enter, go to, hold the pointer
over, press, select, tap, turn on, turn off.

## API reference comments

Source: https://developers.google.com/style/api-reference-comments

Document every class, interface, struct, constant, field, enum, typedef, and
method, including each parameter, return value, and exception. Present tense
throughout.

Open with a verb matched to what the member does:

- "Adds ... and returns" for an operation that returns data.
- "Checks whether" for a boolean getter.
- "Gets the" for other getters.
- "Sets", "Updates", "Deletes", or "Registers" for a void method.
- "Creates a" for a convenience method that constructs the class object.

A class description states the purpose without repeating the class name and
without "This class...".

Parameters: capitalize the first word, end with a period, and start non-booleans
with "The" or "A". Booleans that switch behavior describe both states; boolean state
reads "True if...; false otherwise." Give defaults as "Default: ...". Write "for
example", not "e.g.", because generators can truncate at the period. Don't put *true* or
*false* in code font or in quotation marks here.

Return values: start with "The ..." for anything other than a boolean, and "True
if ...; false otherwise" for a boolean.

Exceptions: where the reference generator inserts the word "Throws", start with
"If ...": "If no key is assigned." Where it doesn't, start with "Thrown when ...":
"Thrown when no key is assigned."

A callback reads "Called by ...".

Every deprecation names its replacement and says how to migrate.

## Verbs in reference documents

Source: https://developers.google.com/style/reference-verbs

Describe what the member does, in third person present tense with the subject
dropped. Don't describe what the developer would use it to do.

| Recommended | Not recommended |
|---|---|
| `tasks.insert`: Creates a new task on the specified task list. | `tasks.insert`: Create a new task on the specified task list. |

*gets*, *lists*, *creates*, *searches*: the `-s` ending is what marks you as
describing rather than instructing.

## Commit bodies

Extension. The subject line takes the imperative mood, at most 50 characters,
no end period.

Present tense for behavior, past tense for what you did. Most important point
first. Wrap the body at 72 characters. The diff already shows what changed, so
don't narrate it. State why the change was needed, what a caller or operator now
has to do differently, and anything you knowingly left worse. No aphorisms, no
superlatives, no "simply".

A commit body describes a change at a point in time, so the timeless-wording ban
in `word-list.md` doesn't apply: *now*, *previously*, and past tense are all
correct here.

## Inline code comments

Extension. A comment carries what the code can't: a constraint, an invariant, a
debt, or the reason for a choice that looks wrong. It doesn't restate the line
that follows it, and it isn't a place for a maxim. Present tense, no hedging, no clever phrasing.