# Mechanics Punctuation, capitalization, numbers, dates, units, abbreviations, and text formatting. From the Google developer documentation style guide; each section names its source page. Guide content © Google, used under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). ## Contents - [Capitalization](#capitalization) - [Commas](#commas) - [Colons and semicolons](#colons-and-semicolons) - [Dashes](#dashes) - [Hyphens](#hyphens) - [Parentheses](#parentheses) - [Periods and end punctuation](#periods-and-end-punctuation) - [Quotation marks](#quotation-marks) - [Slashes](#slashes) - [Ellipses](#ellipses) - [Numbers](#numbers) - [Dates and times](#dates-and-times) - [Units of measurement](#units-of-measurement) - [Mathematical notation](#mathematical-notation) - [Phone numbers](#phone-numbers) - [Abbreviations](#abbreviations) - [Italics with terms](#italics-with-terms) - [Text formatting](#text-formatting) ## Capitalization Source: https://developers.google.com/style/capitalization Use standard American English and nothing more. Sentence case for headings, titles, list items, table cells and headers, captions, and image labels: capitalize the first word, the first word after a colon in a subheading, and proper nouns. Lowercase after a colon, unless what follows is a proper noun, a heading, a quotation, or text after a label such as **Note:**. Don't use capitalization to carry meaning: "Pod" versus "pod" is invisible when read aloud. No all-caps outside official names, standard abbreviations, and code. No camel case outside official names and code. In a hyphenated word starting a sentence or heading, capitalize only the first element. Describe a naming style rather than naming it: "Enter values with no spaces between words and the first letter of each word capitalized—for example, `AssertionAccount`" beats "Use camel case for the field." ## Commas Source: https://developers.google.com/style/commas Serial comma, always: "Locations are divided into zones, regions, and multi-regions." Comma after an introductory word or phrase: "Finally, only groups that contain parameters appear in this list." Comma before a coordinating conjunction joining two independent clauses, unless both are very short. | Recommended | Not recommended | |---|---| | The libraries make feed creation easier, and they ensure that only valid feeds are produced. | ...easier and they ensure... | | Type your ID and click **OK**. | Type your ID, and click **OK**. | Comma before *which* starting a nonrestrictive clause: "Name of the group, which has a maximum length of 200 characters." Punctuation before a conjunctive adverb: "The variable must have a value; otherwise, the server returns an error." Between an independent and a dependent clause joined by a coordinating conjunction, add a comma only if the sentence could be misread without one. Recommended: "Direct-access flags are plain variables and can be read directly." Not recommended: "Direct-access flags are plain variables, and can be read directly." Comma before *because* only when it starts a nonrestrictive clause: "You can use the same key name in multiple backend services, because each set of keys is independent." ## Colons and semicolons Sources: https://developers.google.com/style/colons and https://developers.google.com/style/semicolons Text before a colon must stand alone as a sentence. "The fields are defined as follows:" works; "The fields are:" doesn't. Avoid semicolons where two sentences will do. A semicolon is justified before a conjunctive adverb ("...; therefore, only the stereo cameras are affected") and between list items that carry their own commas. ## Dashes Source: https://developers.google.com/style/dashes Em dash with no space on either side: "To indicate a break in the flow of a sentence—or an interruption—use an em dash." Don't substitute a hyphen or an en dash for it. House deviation: this skill's own prose and output use no em dashes at all. Where the guide would use one, use a comma, a colon, parentheses, or two sentences. The rules in this section still describe the guide. Use them when editing someone else's text against it. Guide examples quoted in this skill keep their em dashes as written; substitute a comma or parentheses when you copy the pattern. Don't use en dashes at all. Use a hyphen or the word *to*. Don't use a dash to separate a term from its description. Use a colon or a period: "Appendix A: My first appendix", not "Appendix A—My first appendix". ## Hyphens Source: https://developers.google.com/style/hyphens Never a space on either side of a hyphen, except after a suspended hyphen. **Compound nouns** default to the closed, one-word form: *webpage*, *hostname*, *tradeoff*, *workaround*. **Prefixes.** No hyphen between a prefix and its noun: *infrastructure*, *megabyte*, *metadata*, *preprocessing*, *pseudocode*, *semiconductor*. Add one when the prefix is *self* or *cross* (*self-managing*, *cross-region*), when the next element is capitalized or a number (*non-Google*, *post-2000*), when it prevents a misreading (*de-energize*, *re-mark*, *re-sign*), when the prefix attaches to an already-hyphenated term (*un-Google-like*), or for consistency within a document (*pre-processing* alongside *post-processing*). *non* is its own case. Closed for *noncurrent*, *nonempty*, *noninteractive*, *nonpublic*; hyphenated for *non-existence*, *non-integer*, *non-key*, *non-managed*, *non-negative*; always hyphenated before an already-hyphenated compound, as in *non-KSA-based*. **Compound modifiers before a noun.** Hyphenate for clarity: *a well-designed app*, *Android-specific techniques*, *more-reliable internet links*. Not needed in *the most common scenario*. Don't build compounds of more than two words. Rewrite instead: "test cases that are specific to the 2023 edition", not "edition-2023-specific test cases". Exception where the term is established: *cross-data-center replication*. **After a verb**, drop the hyphen: *the app is well designed*, *the logs are written in real time*, *the product supports high availability*. Some compounds keep it always: *on-premises*, *add-on*, *cloud-based*, *customer-facing*, *user-friendly*, *game-like*. **Adverbs ending in -ly** aren't hyphenated: *publicly available implementations*. **Numbers and units**: *a 64-bit system*, *100,000-byte files*, *a five-minute wait*. Don't hyphenate an abbreviated unit: `200 GB disk`, `50 Mbps connection`. **Ranges** of bare numbers take a hyphen, not an en dash: *8-20 files*. With *from*, use *to*: "from 8 to 20 files", not "from 8-20 files". A range carrying a unit repeats the unit and joins with *to*. See Units of measurement. **Suspended hyphens** when two compounds share a noun: "one-, two-, or three-hour intervals". ## Parentheses Source: https://developers.google.com/style/parentheses Some readers ignore anything in parentheses, so nothing important goes inside. Keep mid-sentence parentheticals short; if the aside runs long, make it a second sentence. A complete sentence inside parentheses takes its period inside. | Recommended | Not recommended | |---|---| | Enter a name for the instance—for example, `my-instance-99`. | Enter a name for the instance (for example, `my-instance-99`). | | Enter a six-digit hex number (for example, `228B22`), and then click **OK**. | Enter a six-digit hex number (for example, if you want forest green, enter `228B22`), and then click **OK**. | A short parenthetical mid-sentence is fine. At the end of a sentence the guide uses an em dash; this house style uses a comma or a second sentence. ## Periods and end punctuation Source: https://developers.google.com/style/periods End complete sentences with a period, except in headings and some list items; `documents.md` lists the exceptions. One space between sentences. Periods in numbers only as decimal points. Period after a shortened word, none after an acronym. Don't end a sentence with a URL. Rewrite so the URL sits earlier, or put it on its own line with no trailing period. ## Quotation marks Source: https://developers.google.com/style/quotation-marks Straight quotes and straight apostrophes, never curly: code needs straight. Commas and periods go inside the quotation marks. Exception: a literal string in code font takes its punctuation outside. "If you enter `escape`, the program crashes" is right; "If you enter "escape," the program crashes" is not. Single quotes only for nesting inside double quotes, or where a language requires them. ## Slashes Source: https://developers.google.com/style/slashes Avoid slashes outside code. Write *or*, or spell both cases out: "You can export raw events, processed events, or both," not "raw and/or processed events." No slashed abbreviations (*w/*, *c/o*), no slashed fractions (write 0.75 or 75%), no slashed dates. ## Ellipses Source: https://developers.google.com/style/ellipses Avoid ellipses. Where one is unavoidable, use three separate periods rather than the single-character ellipsis, with a space before and after: "...in there ... we'll explain it in class". No space after if punctuation follows. Leave ellipses out when quoting a UI label: a button reading "Save ..." is documented as **Save**. In quoted text, an ellipsis can stand for material dropped from the middle, never from the start or end; where the omission spans a sentence boundary, use four dots. In code samples, mark omitted code with a comment in the language's own syntax instead. In command-line output, `...` on its own line is correct. ## Numbers Source: https://developers.google.com/style/numbers Spell out zero through nine; use numerals for 10 and up. Spell out all ordinals: *first*, *fifth*, *forty-third*. Numerals regardless of size for: version numbers, technical quantities (6 queries per second, 128 bits), page and section numbers, step numbers, prices, mathematical expressions, negative numbers, decimals, and any number under 10 that sits beside one over nine ("15 options but 6 deselected"). Spell out a number that starts a sentence, or better, rearrange so it doesn't. Commas in numbers of four or more digits: 1,532,784. Fractions as decimals: 0.75, with the leading zero. Percentages as numerals with no space: 40%. Dimensions with a lowercase x and no spaces: 192x192. Arabic numerals, not Roman. ## Dates and times Source: https://developers.google.com/style/dates-times Full month name, day, four-digit year: January 19, 2017. For a purely numeric date, ISO 8601: 2017-04-15. Never a slashed date. 12-hour clock, AM and PM capitalized with a space before them, and minutes dropped from round hours: 3 PM, 3:45 PM. A MONTH DAY, YEAR date mid-sentence takes a comma after the year: "The January 19, 2017, release of ...". A month-and-year date takes none: "The January 2017 release of ...". Avoid time zones unless they matter; when they do, spell out the region and put the UTC offset in parentheses: "US and Canadian Pacific Standard Time (UTC-8)". Avoid seasons: hemispheres disagree. Use months or quarters. ## Units of measurement Source: https://developers.google.com/style/units-of-measure Nonbreaking space between the number and the unit: 64 GB, 25 mm. No space for currency ($10), percent (65%), or degrees of angle (180°). Temperature: nonbreaking space between the number and the degree symbol, none between the symbol and the scale: `50 °C`. Kelvin drops the degree symbol and keeps the space: `300 K`. Repeat the unit across a range and join with *to*: "-40 °C to 85 °C", not "-40-85 °C". Hyphenate multiplied units: 5 vCPU-hours, 40 person-hours. Write *per* rather than a slash: "requests per day". Decimal and binary units are different: kB is 1000 bytes, KiB is 1024. Don't write GB when you mean GiB. ## Mathematical notation Source: https://developers.google.com/style/mathematical-notation Italicize variables, never operators: *x* ≠ *y*, *a* − *b*. Use HTML entities for operators rather than keyboard symbols. `+`, `=`, and `/` use the keyboard characters. Put a nonbreaking space on both sides of each operator so the expression doesn't wrap: *y* = *a* + *bx*. Keep short expressions inline. Use `` and `` for exponents and subscripts, with no space between base and exponent: 2³, not `2^3`. Express fractions as decimals when you can: 0.02. Notation can replace words in running text: "Check whether *a* > *b*" is preferred over "Check whether *a* is greater than *b*". ## Phone numbers Source: https://developers.google.com/style/phone-numbers In an example, use only the reserved range 800-555-0100 through 800-555-0199, never a real number. A real number, such as a published support line, takes the same formatting rules. Hyphens between area code, exchange, and line number: 415-555-0132. A country code takes a leading plus and no space: +1-415-555-0132. An extension follows the word *extension*: "415-555-0132, extension 987". Use nonbreaking hyphens (`‑`) so the number doesn't wrap. ## Abbreviations Source: https://developers.google.com/style/abbreviations Spell out an unfamiliar abbreviation on first mention with the abbreviation in parentheses, and italicize both: "Establish *Border Gateway Protocol* (*BGP*) sessions...". Use the abbreviation alone after that. If the term appears once, skip the abbreviation entirely. Capitalize the spelled-out form only if it's a proper noun or is conventionally capitalized, not merely because the abbreviation is uppercase. Recommended: *data manipulation language* (*DML*). Not recommended: *Data Manipulation Language* (*DML*). No periods in acronyms or initialisms. Don't use an acronym as a verb: "Use SSH to log in to your remote shell," not "Then ssh into your remote shell." Don't use *i.e.* or *e.g.*; write *that is* and *for example*. ## Italics with terms Source: https://developers.google.com/style/italics-terms Italicize a term at the point you define it, and only there: "A *Clos network* is a kind of multistage circuit switching network." Not bold, not quotation marks. Italicize a word you're discussing as a word: "Don't use *&* as a conjunction. Use the word *and* instead." ## Text formatting Source: https://developers.google.com/style/text-formatting | Item | Format | |---|---| | UI elements | bold | | Run-in headings, notice labels ("**Note:**") | bold | | A term at the point you define it | italic | | A word used as a word | italic | | Book, film, and series titles | italic | | Mathematical variables, version variables | italic | | Code, filenames, paths, class and method names, HTTP status codes, console output | code font | | Placeholders | code font, italic where the renderer allows | Bold is only for UI elements and run-in headings, including the label that opens a notice. For emphasis, use italics, never bold or underline. No underlining except for links. Don't use an ampersand for *and* unless it's the literal label of a UI element.