google-developer-style-guide-punctuation

name	google-developer-style-guide-punctuation
description	Punctuation rules from the Google developer documentation style guide. Covers commas, colons, semicolons, dashes, hyphens, periods, ellipses, slashes, apostrophes, and quotation marks.

Google developer documentation style guide—punctuation reference

Commas

Serial (Oxford) comma

Always use a comma before the final and / or in a series of three or more items.

Do	Don't
zones, regions, and multi-regions	zones, regions and multi-regions

After introductory words/phrases

Place a comma after an introductory word or phrase.

• ✅ Finally, only groups that contain parameters appear in this list.
• ✅ Based on the requirements of your game, you can implement this method.

Two independent clauses joined by a coordinating conjunction

Insert a comma before the conjunction (and, but, or, nor, for, so, yet)— unless both clauses are very short.

Do	Don't
The libraries make feed creation easier, and they ensure valid feeds.	The libraries make feed creation easier and they ensure valid feeds.
Type your ID and click OK.	Type your ID, and click OK.

Independent + dependent clause

Add a comma only if the sentence could be misread without one.

Do	Don't
Direct-access flags are plain variables and can be read directly.	Direct-access flags are plain variables, and can be read directly.
The manager acknowledged the last team member who entered the room, and started the meeting.	The manager acknowledged the last team member who entered the room and started the meeting.

Nonrestrictive clauses

• Put a comma before which at the start of a nonrestrictive clause.
• Put a semicolon/period/dash before a conjunctive adverb (otherwise, however, therefore) and a comma after it.
• Don't put a comma before because unless it starts a nonrestrictive clause.

Do	Don't
Name of the group, which has a maximum length of 200 characters.	Name of the group which has a maximum length of 200 characters.
The variable must have a value; otherwise, the server returns an error.	The variable must have a value otherwise the server returns an error.
...backend services and backend buckets, because each set of keys is independent...	...backend services and backend buckets because each set of keys is independent...

---

Colons

Before a list

The text preceding a colon must be a complete sentence.

Do	Don't
The fields are defined as follows:	The fields are:

Within sentences

Lowercase the first word after a colon (exceptions: see capitalization rules).

• ✅ Tone: concise, conversational, friendly, respectful
• ✅ ...remember to take these steps: review the style guide, use checklists, enlist a fellow writer...

Colons instead of dashes in description lists

Use a colon or period (not em dash, en dash, or hyphen) to separate an item from its description.

Do	Don't
Example: This is an example.	Example - This is an example.
Appendix A: My first appendix	Appendix A—My first appendix

---

Semicolons

Avoid semicolons when possible. Acceptable uses:

1. Joining two closely related independent clauses where a period or comma is less effective.
   • ✅ You can easily test compatibility by computing the centroid; if it is on the opposite side of the planet, reverse the order.
2. Before a conjunctive adverb (therefore, that is) joining two independent clauses.
   • ✅ ...places the head-tracked node below the Main Camera; therefore, only the stereo cameras are affected.
   • ✅ The URL from which a video ad loads; that is, the URL to use to fetch that video ad.
3. Separating long/complex series items that contain their own punctuation.
   • ✅ ...focus on: what matters most to your users; what is most important to fix; and what is easy or feasible to fix.
   • ✅ ...checking for the following: present tense and active voice; typos, punctuation, and grammar; and whether you can shorten anything.

---

Dashes (em dash)

Use an em dash (—) for a break or interruption in a sentence. No spaces before or after.

• Input methods: HTML — · macOS Option+Shift+hyphen · Windows Alt+0151 (numpad)

En dashes—don't use

Use a hyphen or the word to instead. Never substitute an en dash for an em dash.

Colons instead of dashes

In description lists, use a colon—not a dash—to separate item from description (see Colons section).

---

Hyphens

Use a hyphen (-) when needed for clarity—to avoid misreadings or to combine terms read as a unit.

Resolution order for uncertain hyphenation

1. Established convention in your documentation set
2. Google style guide word list
3. Merriam-Webster dictionary

Prefixes

General rule: No hyphen between prefix and main noun (infrastructure, megabyte, metadata, preprocessing).

Exceptions—add a hyphen when:

Condition	Examples
Prefix is self or cross	self-managing, cross-region
Noun is capitalized or a number	non-Google, post-2000
Avoids confusion / hard to read	de-energize, re-mark, re-sign
Base term already has hyphens/spaces	un-Google-like, non-twentieth-century
Consistency within a document	pre-processing, post-processing

The non prefix: Follows general rules, but hyphenate when the closed form is hard to parse. Use judgment; be consistent.

• Closed OK: noncurrent, nonempty, noninteractive, nonpublic
• Hyphenated: non-existence, non-integer, non-key, non-managed, non-negative
• Before hyphenated compounds: non-KSA-based, non-self-sustaining

Compound nouns

Prefer closed (one-word) form: webpage, hostname, tradeoff, workaround.

Exception: Check word list for established hyphenated/open forms (multi-region, style sheet).

When units of measurement are multiplied: hyphenate (5 vCPU-hours, 40 person-hours).

Compound modifiers before a noun

Hyphenate for clarity.

Do	Don't / Notes
a well-designed app	—
Android-specific techniques	—
Edge locations with more-reliable internet links	Hyphenate after more/most if needed for clarity
cross-data-center replication	Avoid 3+ word compounds; move words after noun if possible

Numbers + spelled-out units before a noun: Hyphenate.

• ✅ a 64-bit system, 100,000-byte files, a five-minute wait

Abbreviated units: Don't hyphenate; use   between number and unit.

• ✅ 200 GB disk, 50 Mbps connection

Adverbs ending in -ly: Don't hyphenate.

Do	Don't
Publicly available implementations	Publicly-available implementations

Conventionally unhyphenated compounds: Follow word list / documentation convention.

• ✅ A managed instance group, A machine learning model

Compound terms after a verb

Generally no hyphen after a verb.

• ✅ The app is well designed.
• ✅ The logs are written in real time.
• ✅ Customers can use the utility as is.

Exception: Some compounds are always hyphenated (check word list / Merriam-Webster).

• ✅ You can deploy the app on-premises.
• ✅ The utility works with apps that are cloud-based and cloud-adjacent.
• ✅ The app is designed to be user-friendly.

Number ranges

Use a hyphen (not en dash) for ranges. Don't mix hyphens with words.

Do	Don't
8-20 files	—
from 8 to 20 files	from 8-20 files

Spaces around hyphens

Never space either side—except suspended hyphens (space after, not before).

Suspended hyphens

When compound modifiers share a common base, keep hyphens but omit the base except on the last.

• ✅ one- or two-hour intervals
• ✅ one-, two-, or three-hour intervals

---

Periods

Sentences

Always end complete sentences with a period (except questions, and certain list items/headings).

With lists

See the Lists section in the google-developer-style-guide-structure skill for rules on end punctuation in list items.

With URLs

Avoid placing a URL at the end of a sentence. If unavoidable, no space between URL's last character and the period. Techniques:

• Rewrite so URL isn't sentence-final.
• Place URL on its own line, omitting the period.

Do	Don't
...Privacy Policy: http://example.com/privacy/	...Privacy Policy at http://example.com/privacy/.

With quotation marks

Period goes inside quotation marks—unless quoting a keyword/literal string (see Quotation marks section).

• ✅ ...you might say "Fixed typo."
• If quoted material ends with ? or !, omit the period: Children always ask "Why?"

With parentheses

Scenario	Rule
Parenthetical at end of sentence	Period after closing paren.
Parentheses enclose a complete standalone sentence	Period inside closing paren.

• ✅ ...(even if that change occurs while your application isn't running).
• ✅ (With App Engine, there are no servers for you to maintain.)

Headings

Don't end headings with periods.

Numbers

Use a period for decimal points (not a comma).

Abbreviations

Period after shortened words; no periods in acronyms/initialisms.

Sentence spacing

One space between sentences.

Exclamation points

General rule: avoid.

Content type	Guidance
Concept/reference docs	Never
Procedural topics	Avoid; use periods
Blog posts	Acceptable sparingly for enthusiasm
Code examples	OK when required by syntax (e.g., !=)
System literals	OK when part of exact error code/message
Tutorials	Sparingly for milestones: Congratulations! You've completed the setup.

---

Ellipses

General rule: Don't use ellipses in documentation.

Don't use as suspension points

• ❌ The answer is ... wait for it ... that you shouldn't do this.

In UI references

Omit ellipses from UI element names unless omission causes confusion. Save ... → document as click Save.

In text

Don't use in original text. Acceptable only in quoted text to replace omitted portions—but never at the beginning or end of the quote.

Do	Don't
"All the world's a stage, .... And one man in his time plays many parts."	"All the world's a stage, And all the men and women merely players ...."
—	" ... all the men and women merely players."

Four dots: When omitted material spans a sentence boundary, use four periods (the fourth is the sentence-ending period).

Formatting

• Use three actual periods (...), not the ellipsis character (…).
• One space before and after—unless a punctuation mark immediately follows (then no space after).

Do	Don't
...code in there ... we'll explain...	...code in there...we'll explain...
...code in there ...; we'll explain...	—

---

Slashes

General rule: Avoid slashes except in code, file paths, and URLs.

Dates

Don't use slash-based date formats.

Alternatives

Don't use slashes to separate alternatives; spell out and / or.

Do	Don't
...developed and is hosted by...	...developed/hosted by...
Call this method five or six times.	Call this method 5/6 times.

And/or

Often and implies or. Avoid and/or except where space is limited (e.g., tables).

Do	Don't
You can view and edit your own data.	You can view and/or edit your own data.
...raw events, processed events, or both.	...raw and/or processed events.

File paths and URLs

Forward slashes are fine in paths/URLs. Break long URLs immediately after a slash; never insert a hyphen.

Fractions

Don't use slashes (ambiguous). Use fraction characters, decimals, or percentages.

Do	Don't
¾ / 0.75 / 75%	3/4

Abbreviations

Don't use slash-based abbreviations; spell out.

Do	Don't
care of, with	c/o, w/

---

Apostrophes and possessives

Straight apostrophes

Always use straight apostrophes ('), not curly/typographic (’).

Forming possessives

Noun type	Rule	Example
Singular (including ending in s)	Add 's	each vector's record, the storage class's quota
Plural ending in s	Add only '	the models' capabilities
Plural not ending in s	Add 's	(standard English rule)

If a possessive is awkward, rewrite.

Do	Don't
Analyze the business data.	Analyze the businesses' data.
The rule that the FTC issued.	The Federal Trade Commission's (FTC's) rule.

Don't use 's to form plurals

Product, feature, and trademark names

Don't form possessives from product/feature names or trademarks when describing function/performance. Use the name as a modifier or rewrite with of.

Do	Don't
...monitor Google Search performance.	...monitor Google Search's performance.
...monitor the performance of Google Search.	—

Company name possessives are OK for non-trademark uses: Google's new office is nearby.

Code items

Never form a possessive from a code item. Possessive goes on the following noun, or rewrite.

Do	Don't
the wordCount method's return value	wordCount's return value
the value returned by the wordCount method	—

---

Quotation marks

Use straight double quotation marks

Always use straight (""), not curly/typographic (“”), in developer documentation.

Reasons: Code requires straight marks; auto-curling tools and humans make mistakes; hard to proofread; difficult to type on some platforms.

When to use quotation marks

Use case	Example
Title of shorter work (article, episode) not linked	...described in the section "Deploying containers" of the video.
Title of parent doc when linking to a subsection	The ML workflow section of "Introduction to Vertex AI"...
Direct quotation / slogan	Martin Fowler has said, "We are still learning..."
Metaphorical use of a term (not established domain usage)	This forms an "island" within the network.

Full-length work titles: use italics, not quotation marks.

Commas and periods with quotation marks

Commas and periods go inside quotation marks.

Do	Don't
See the section titled "Care and feeding of the emu."	See the section titled "Care and feeding of the emu".

Exception—literal/keyword strings: Put punctuation outside quotation marks to preserve the exact literal.

Do	Don't
If you enter "escape", the program crashes.	If you enter "escape," the program crashes.

Prefer code font over quotation marks for literals: If you enter escape, the program crashes.

Single quotation marks

Use only for:

1. Code examples in languages that use single quotes.
2. Nested quotations (single inside double).

Do	Don't
She said, "I heard him shout 'Help,' and saw him..."	She said, 'I heard him shout "Help", and saw him...'