diff options
Diffstat (limited to 'skills/google-style-guide/reference/code.md')
| -rw-r--r-- | skills/google-style-guide/reference/code.md | 105 |
1 files changed, 105 insertions, 0 deletions
diff --git a/skills/google-style-guide/reference/code.md b/skills/google-style-guide/reference/code.md new file mode 100644 index 0000000..cb5af34 --- /dev/null +++ b/skills/google-style-guide/reference/code.md @@ -0,0 +1,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.
\ No newline at end of file |