Punctuation

Capitalization

We should capitalize only when there is a good reason for doing so. Otherwise, capitalization can creep into lots of areas where it has no place.

One situation where this often happens is in the context of common abbreviations and acronyms.
We might think that, because capital letters are used in an acronym, we should also use capital letters when the term is written out in full.
This is usually not the case, unless the term is a proper noun. (See Proper Nouns.)

AbbreviationFull expression

CLI

command line interface

MFA

multi-factor authentication

SaaS

software as a service

JDK

Java Development Kit [proprietary name]

Colon (“:”)

The function of a colon in a sentence is to signal the beginning of an explanation or a list.
Often, we can think of it as saying, and it is this…​ or and this is what I’m talking about…​.
Some examples of this are:

There can be only one reason he is late: he has missed the flight.
Annabel has three valuable characteristics: she is clever, she is conscientious, and she is honest.
On seeing the results of my work, I felt only one emotion: pride.

A colon is also commonly used to introduce a list, particularly at the end of a sentence.
For example:

The parameter can be of several types: integer, boolean, or string.
Three cities are in the running to stage the next Olympics: Beijing, Chicago, and Melbourne.

A colon should not be used to join two full clauses outside the uses mentioned here.
If you are looking for the right punctuation to join two clauses that have some logical relationship, consider using a semi-colon.
Do not use a comma for this purpose. (See Comma Splice.)

Vaadin uses US English in its documentation. US usage allows a colon to be followed by a sentence beginning with a capital letter, if that sentence is the first of two or more sentences that are governed by the same colon.

There may be several reasons to learn Esperanto: It is completely regular, so you do not need to learn a lot of exceptions. It is not associated with any specific country, so has no political baggage. Finally, it is just fun to learn.

However, if the colon governs only one sentence, begin the sentence with a lowercase letter:

I can give you one good reason to learn Esperanto: it is fun to learn.

Comma Splice

Consider the following (incorrectly punctuated) sentence:

You should never divide by zero, this will cause a runtime error.
[Incorrect]

In this example, we have two complete clauses, as each one has a subject and a finite (full) verb. It is an error to join the two clauses with a comma. This error is often called a comma splice. (Splice means join.)

We have several options to rectify this error. The simplest option is to make each clause a sentence on its own:

You should never divide by zero. This will cause a runtime error.

This solution is grammatically correct. However, it does not show the logical connection between the two clauses. A better option would be to use different punctuation. A semi-colon would serve the purpose:

You should never divide by zero; this will cause a runtime error.

Unlike a comma, a semi-colon can be used to join two complete clauses. Moreover, it implies a logical connection between them, although the specific logic is left to the reader’s interpretation. (See Semi-Colon.)

Another option would be to use an appropriate conjunction. As its name suggests, a conjunction is a joining word. Some common conjunctions are: and, but, or, because, as and so. Conjunctions often imply some kind of logical connection between the clauses that they join.

In our example, we want to express a concept of causation. Because and as would be suitable options:

You should never divide by zero, because this will cause a runtime error.
You should never divide by zero, as this will cause a runtime error.

Although the meaning of these two versions is the same, in fact, by convention, we use as more often than because to express this kind of causation. Consequently, the second version is the best of the options that we have discussed.

Commas

In a small number of situations, commas are mandatory in English. These include:

Double Quotes (“)

Em Dash ("—")

In US English, a pair of em dashes (so called because they have the same width as the letter M) are used to indicate a fragment of text in parenthesis. The pair of em dashes imply a more significant break in the structure of the sentence than one marked by a comma or brackets. There should be no space either before or after an em dash. For example:

The tool does not fix the bug—if only it were that simple—but it does help you to identify its location.

You can use a dropdown or a combo—personally, I prefer the latter—but, either way, the user needs to be able to select from the available options.

A single em dash can be used to add an afterthought or aside. For example:

You can use whichever IDE you prefer—it is entirely up to you.

Make sure your code is well commented—you will thank yourself when you revisit it six months later.

Avoid using the em dash too much; it can quickly become distracting and even irritating. Very often, a comma or semi-colon is a more appropriate choice of punctuation, especially in more formal writing, such as technical documentation. The two previous examples could also be written as:

You can use whichever IDE you prefer; it is entirely up to you.

Make sure your code is well commented; you will thank yourself when you revisit it six months later.

En Dash ("–")

The en dash (so called because it has the same width as the letter N) is commonly used to indicate a range of values. When used in this way, it is not preceded or followed by a space. For example:

Select a number in the range 0–255.

The parameter should be a string of 8–10 characters.

The licence enables you to use the software on 1–3 computers.

He was chief designer (2003–9), and subsequently CEO of the company (2009–12).

The office is open Monday–Friday.

We can also describe ranges by using the words from and between. These forms should not be mixed with the en dash. Use one form or the other, but not both. For example:

You can use the licence on between 1 and 3 workstations.
[Not between 1–3 workstations.]

The parameter should be a string of from 8 to 10 characters.
[Not a string of from 8–10 characters.]

Headings

You should use title or headline case for all headings and chapter, section, or sub-section titles.

= Style Guidelines for Vaadin Documentation

For a detailed description of capitalization rules, see for example:

Hyphen (“-”)

An issue that often causes confusion is whether or not to use a hyphen in compound words (such as start-up and onboarding) and words that include a prefix (such as presales and multifactor). English has no hard-and-fast rules about this; it is simply a question of accepted usage.

In general, use the Merriam-Webster online dictionary as a guide. If the full compound word or prefixed word exists in the dictionary, use the form that the dictionary gives. If the full compound word or prefixed word does not exist in the dictionary, use a hyphen. For example:

start-up (noun)
[This is the form given in the dictionary.]

setup (noun)
[This is the form given in the dictionary.]

log-in (noun) [Neither log-in nor login is given in the dictionary, so use a hyphen.]

Sometimes, we want to mention a series of items, all hyphenated on the same base word. In such cases, we can reduce repetition by applying distributed hyphenated descriptive words to the base word. For example:

The device used a combination of first-generation and second-generation chips.
[OK, but repetitive.]

The device used a combination of first- and second-generation chips.
[Better.]

In general, use a hyphen in compounds formed from an adverb and an adjective, in order to avoid ambiguity as to which word the adverb qualifies. For example:

I am grateful to my hard-working colleagues. Not hard working colleagues.

This benefits low-paid employees. Not low paid employees.

However, do not use a hyphen when the adverb ends in -ly.

In these cases, there is no ambiguity concerning which word the adverb applies to. For example:

The technology is a closely guarded secret. Not closely-guarded secret.

This benefits poorly paid employees. Not poorly-paid employees.

Lists

Items in a list can be separated by commas.
If a list contains three or more items, and the last item is preceded by a conjunction (and, or), place a comma before the conjunction.
This use of a comma is called the Oxford comma.
For example:

The team includes analysts, developers, and testers.

Leave a comment in the forum if you have any doubts, queries, or suggestions.

In cases where items in the list themselves contain commas, it is better to use semi-colons as item separators, in order to avoid confusion.
For example:

This curry has three vital ingredients: onion, potato, and spinach.

This curry has three vital ingredients: onion, which should be roughly chopped; potato, which should be diced; and fresh spinach leaves, which should be thoroughly washed before use.

Non-Breaking Space

Use a non-breaking space to prevent the browser from splitting terms in a way that could cause confusion for the reader. Some examples are:

  • between a number and its units

  • between numbers and words that define a date

  • between a person’s title (Ms, Dr, Prof.) and their name

  • between words separated by a slash ("/") character

A non-breaking space can be written in AsciiDoc as  .

Oxford Comma

See Lists.

Product Names

Product names, such as List Box, should be capitalized as is usual for proper nouns, not as if they were class names. Use the class name if you are referring specifically to a class. For example:

ListBox extends ListBoxBase.

However, do not use class names in component documentation, which should be language-independent; that is, neither Java- nor JavaScript-specific.

Quotation Marks

In general, when you want to put text in quotation marks, use double quotation marks (" "). Avoid using single quotation marks (' '), unless, of course, it is required by some code syntax.

Semi-Colon (“;”)

Single Quotes (‘ ’)