Punctuation

Colons

The first word after the colon should be in uppercase.

Colons preceding lists

When a colon introduces a list, the phrase before the colon must be a complete sentence.

A colon cannot be placed between a verb and its object or a preposition and its object. See Lists.

Incorrect

The methods are:

Correct

The SDK uses the following methods:

  • joinChannel

  • leaveChannel

  • renewToken

Colon use within sentences

Do not use colons within sentences. In most cases, splitting the two clauses into separate sentences reads better and is more clear.

Colon use in ratios

No space before or after a colon when it is used to express ratios.

Commas

General rules to follow:

  • In a series of three or more items, use a comma before the final “and” or “or.” (This is the house editing style of Oxford Press, hence the term “Oxford comma”).

    Example

    Adds support for the macOS, Windows x86, and Windows x86_64 platforms.

  • In general, place a comma after an introductory word or phrase like “occasionally”, or “otherwise”.

    Example

    Occasionally, the SDK does not automatically reconnect after being disconnected from the servers for pushing and pulling streams.

  • When a coordinating conjunction (“for”, “and”, “nor”, “but”, “or”, “yet”, and “so”) separates two independent clauses (where each clause could stand as an independent sentence), insert a comma after the first clause before the conjunction. For example: “The recorded files are stored on your server only, and Agora has no access to them.” An exception is when both clauses are very short. For example: “Enables or disables image enhancement and sets the options.”

  • Commas also enclose the following and similar phrases: “and so forth,” “for example,” “namely,” and “that is,”.

Recommended

Not recommended

Unity renders 3D objects by default, such as Cube, Cylinder**,** and Plane. (note comma after “Cylinder”)

Unity renders 3D objects by default, such as Cube, Cylinder and Plane.

Finally, only groups that contain parameters appear in this list.

Finally only groups that contain parameters appear in this list.

The libraries not only make feed creation easier, but they also ensure that only valid feeds are produced.

The libraries not only make feed creation easier but they also ensure that only valid feeds are produced.

Ampersands

Do not use ampersands (“&”) unless they are part of a name, UI string, or in a piece of code.

Exclamation marks

Do not use exclamation marks unless they are part of a code example.

Periods

General rules to follow:

  • Use a period to end a complete sentence.

  • Do not use a period at the end of a sentence fragment, such as an item in a list that is not a complete sentence, or in a heading title.

  • Do not use a period in a title or heading.

  • List items that are complete sentences end with a period.

  • List items that are incomplete sentences do not end with a period. However, when a list includes one item that requires a period, all the list items should have a period for consistency.

  • For table items, use complete sentences and end them with a period.

Slashes

Use a slash to separate the two functions that can be realized with one method, such as, “enable/disable”. The capitalization of the two words should remain consistent.

Do not use slashes to separate alternatives. For example use “audio or video calls” instead of “audio/video calls”.

Hint

“a and/or b” is only acceptable when the meaning is a or b or both.

Hyphens

In appearance, a hyphen is shorter than both the em dash (“—”), and the en dash (“–”).

  • All words following a hyphen are in lowercase, even if the word is at the beginning of a sentence. For example, “32-bit” or “Open-source”.

  • Use a hyphen to form a compound adjective which is an adjective made up of more than one word. Examples include, “A 25-minute interval”, “16-bit color”, “state-of-the-art technology”, “a six-figure price”.

  • Use a hyphen to indicate a common second element. For example, “a 10- to 11-digit number”, “a six- or seven-hour delay”, “a two-, three-, or fourfold increase”.

  • Many common prefixes, such as “co”, “de”, “pre”, “pro”, “re”, and “sub” do not need a hyphen.

  • Do not use a hyphen when forming a compound adjective with an adverb that ends in “ly”.

Recommended

Not recommended

A badly written book.

A badly-written book.

Semicolons

The semicolon has the following uses:

  • To unite sentences that are closely associated

    Example

    The people on the fourth floor work with product development; those on the fifth work with deployment.

  • To create a stronger division in a sentence that already includes divisions using commas

    Example

    The people on the fourth floor, who work with product development, are to continue with the project until Friday; but the following Monday, when their equipment has been moved, they resume work on the sixth floor.

  • To create stronger divisions in a list

    Example

    The visitors are to be received by the managing director, Daphne Jones; the head of security, Fred Smith; and the union representative, Howard Brown.

Caution

The previous examples only demonstrate the semicolon usage and are not typical of technical writing style.

Spaces

General rules to follow:

  • Add a space before an opening parenthesis (. Example: Basic Methods (RTCEngine)

  • Use only one space after full stops. Example: Add a space. One after the full stop.

  • Use one space between numbers and units. Example: 256 Kbps.

  • Use spaces around mathematical symbols. Example: V = off, width x height, x < y

  • Use spaces around dimensions. Example: 3.2 x 3.6 x 0.6 mm.

Exception

There is no space before a parenthesis when writing a function call. For example:

  • muteRemoteAudioStream(true)

  • enableLocalVideo(false)

  • CHANNEL_PROFILE_COMMUNICATION(0)