Documentation versions (currently viewingVaadin 23)
New Acceleration Kits: Observability Kit, SSO Kit, and Swing Kit. Read the blog post.



You 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.
You might think that, because capital letters are used in an acronym, you 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.)

Abbreviation Full expression


command line interface


multi-factor authentication


software as a service


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, you can think of it as saying, and it’s 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 shouldn’t 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.
Don’t use a comma for this purpose. (See Comma Splice.)

Vaadin uses U.S. English in its documentation. U.S. 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 don’t need to learn a lot of exceptions. It isn’t associated with any specific country, so has no political baggage. Finally, it’s 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 causes a runtime error.

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

You 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 causes a runtime error.

This solution is grammatically correct. However, it doesn’t 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 causes 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 this example, you want to express a concept of causation. Because and as would be suitable options:

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

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


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

Double Quotes (“)

Em Dash ("—")

In U.S. English, a pair of em dashes (so called because they have the same width as the letter M) are used to mark 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 doesn’t fix the bug—if only it were that simple—but it does help you to identify its location.

You can use a drop-down 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’s entirely up to you.

Make sure your code is well commented—you’ll 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’s entirely up to you.

Make sure your code is well commented; you’ll 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 display a range of values. When used in this way, it isn’t 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 license 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.

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

You can use the license 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.]


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 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’s only 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, you want to mention a series of items, all hyphenated on the same base word. In such cases, you 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.

In general, use a hyphen in compounds formed from an adverb and an adjective, to avoid ambiguity 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, don’t 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.


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’s better to use semi-colons as item separators, 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, don’t 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’s required by some code syntax.

Semi-Colon (“;”)

Single Quotes (‘ ’)