> Markdown version of [Grammar](https://vaadin.com/docs/v23/contributing-docs/style-guide/grammar). Section index: [llms.txt](https://vaadin.com/docs/v23/contributing-docs/llms.txt)

# Grammar

<!-- vale Vaadin.FirstPerson = NO --><!-- vale Vaadin.We = NO -->

## <a id="abbreviations"></a>Abbreviations

Don’t terminate abbreviations with a period if the last letter of the unabbreviated form is included in the abbreviation. For example:

<!-- vale Vale.Spelling = NO -->

*Mr Smith*\
*Mrs Smith*\
*Ms Smith*\
*Prof. Smith*\
*Dr Smith*\
*St Petersburg*\
*Microsoft Corp.*\
*M. Duval* \[abbreviation of the French word *monsieur*]

<!-- vale Vale.Spelling = YES -->

In general, plurals of abbreviations are formed by adding a lowercase *s*. Don’t use apostrophe *s* (*’s*) for this purpose.\
For example:

<!-- vale Vaadin.Abbr = NO -->

*SOPs*\
\[abbreviation for *standard operating procedures*; not *SOP’s*]

*APIs*\
\[Not *API’s*.]

Commonly known abbreviations are listed in `.github/styles/Vaadin/Abbr.yml`.

<!-- vale Vaadin.Abbr = YES -->

See also [Latin Abbreviations](https://vaadin.com/docs/v23/contributing-docs/style-guide/style.md#latin-abbreviations).

## <a id="grammar.adverb_phrases"></a>Adverb Phrases

If you begin a sentence with an adverb phrase, place a comma after the phrase.\
For example:

***Unfortunately,** we can’t reproduce the bug.*\
***As you can see,** the screen layout is logical.*\
***This morning,** I spoke to our customer services manager.*

## <a id="angle-brackets"></a>Angle Brackets

In general text,the name for the *<* and *>* characters is *angle brackets*.\
In other contexts, the same characters are known as the *less than* and *greater than* symbols.

## <a id="grammar.apostrophe"></a>Apostrophe (’)

The apostrophe has a specific function: to show when one or more letters have been omitted. For that reason, it’s used in contracted forms of verbs.

However, to show the function of the apostrophe in contractions in general, here are some examples:

*I am* → *I’m*\
\[The letter *a* is omitted.]

*She is* → *She’s*\
\[The letter *i* is omitted.]

*They are not* → *They aren’t*\
\[The letter *o* is omitted.]

<!-- vale Vaadin.Wordiness = NO -->

In some cases this logical system of contraction has been adapted, by convention and usage. For example:

<!-- vale Vaadin.Wordiness = YES -->

<!-- vale Vale.Spelling = NO --><!-- vale Vaadin.Will = NO -->

*He will not* → *He won’t*\
\[A little illogical, but it’s the accepted contraction.]

*We shall not* → *We shan’t*\
\[And not, for example, *sha’n’t*.]

<!-- vale Vaadin.Will = YES --><!-- vale Vale.Spelling = YES -->

The other standard use of the apostrophe in English is to signify possession.

In fact, this has its logic. In Old English, the possessive case of a noun was formed by adding *-es* to it.

In modern English, the *e* has been dropped from that suffix; this omission is now marked by that apostrophe.

The possessive form of a **single** noun is formed by adding *’s*. For example:

*The developer’s guide*

*The boss’s office*

The possessive of a **plural** is formed by the following process:

- write the ordinary plural form

- if that plural form already ends in *s* (the commonest case), place the apostrophe **after** that *s*

- in the few irregular cases where the plural form doesn’t end in *s* (for example, *men*, *women*, *children*, *sheep*), add *’s*, as for a single noun

For example:

*The employees’ salaries*\
*The bosses’ salaries*\
*The women’s records*\
*The mice’s tails*

For when to form a possessive using an apostrophe, and when to use *of*, see [Possessive](https://vaadin.com/docs/v23/contributing-docs/style-guide/style.md#style.possessive).

## <a id="grammar.apposition"></a>Apposition

Consider this sentence:

*The CEO, Nick Smith, spoke to a company employee.*

In this sentence, *The CEO* and *Nick Smith* identify the same entity (in this case, a person). In other words, *Nick Smith* is another name for *the CEO*.

In the terminology, the phrase *Nick Smith* is "in apposition" with *the CEO*.\
Notice that the phrase that’s in apposition is delimited by commas.

Now, consider this sentence:

*The CEO, Nick Smith, spoke to company employee Susan Rae.*

In this case, *company employee* and *Susan Rae* do **not** identify the same entity.\
It’s likely that there is only one *Susan Rae* in this context, but there are, no doubt, many company employees. In other words, *Susan Rae* isn’t another name for *company employee*.

Hence, *Susan Rae* is **not** in apposition with *company employee* and, for that reason, isn’t delimited by commas here.

Let’s look at an example that’s more relevant to the context of technical documentation.\
Here is some information about the parameters of a method.

*The method takes a single parameter: `duration`.*\
*The method’s parameter, `duration`, specifies the time in milliseconds that the animation should run.*

Here, as there is only one parameter, *the method’s parameter* and *duration* refer to the same entity. *Duration* is in apposition with *the method’s parameter*, and so is delimited by commas.

Now, here is some similar information but, this time, the method takes more than one parameter.

*The method takes two parameters: `startTime` and `duration`.*

*The parameter `duration` specifies the time in milliseconds that the animation should run.*

Here, *parameter* and *duration* don’t mean the same thing. For this reason, *duration* isn’t in apposition with *parameters*, so it’s **not** delimited by commas.

## <a id="articles"></a>Articles

Missing and misused articles (*a*, *an*, *the*) are a very common problem, especially for speakers of languages which don’t have articles, such as Finnish, Russian, and Japanese.

Although the basic concept of articles is quite simple, there are some special cases and exceptions that can complicate the issue. You may find the following useful:

<!-- vale Vale.Spelling = NO -->

- [Grammarly Handbook](https://www.grammarly.com/handbook/grammar/articles/) about the use of articles (in English)

- [Yksikkö, monikko ja artikkelit](https://englantia.wordpress.com/grammar/yksikko-monikko-ja-artikkelit/) (in Finnish)

- [Articles](https://materiaalit.internetix.fi/fi/kielet/englanti11/e1_lesson2.htm) (in Finnish)

<!-- vale Vale.Spelling = YES -->

## <a id="conditional"></a>Conditional

## <a id="grammar.contractions"></a>Contractions

Contractions (or "contracted verb forms") are those where one or more letters are omitted. For example:

<!-- vale Vaadin.Will = NO -->

She’s on her way to the meeting. \[*She’s* is a contraction of *she is*.]

They’ll be here on Friday. \[*They’ll* is a contraction of *they will*.]

<!-- vale Vaadin.Will = YES -->

In general use, contractions are perfectly acceptable and correct. In fact, using contractions can help to make a non-native speaker’s English sound much more natural.

However, contractions aren’t generally appropriate in formal contexts, such as academic works and legal documents.

## <a id="grammar.countable_entities"></a>Countable and Uncountable Entities

Some entities have the characteristic of existing as separate objects, such that we can count them.\
For example, books are objects that exist separately from each other, so that it makes sense to talk about *one book*, *two books*, and so on.\
We call this category of objects *countable*.

We view some other entities as existing in bulk, as amounts of something, rather than many separate objects that we can count.\
For example, we apply the label *air* to a contiguous body of gaseous substances. It doesn’t usually make sense to talk about *one air* or *two airs*.\
The same applies to entities such as *sugar*, *water*, and aluminum.\
We call this category of entities *uncountable*.

From the point of view of grammar, it’s important to consider whether some entity is countable.\
For example, the indefinite articles, *a* and *an*, convey the meaning of *one* of something.\
Hence, it makes sense to use them with countable nouns, but not with uncountable ones.\
The phrases *an air* or *a water* have no meaning.

Similarly, countable nouns, by definition, can be plural.\
Uncountable nouns, again by definition, can’t be plural.

However, there is a small trap here.\
Many nouns can’t be categorically defined as either countable or uncountable; it depends on their meaning in the given context.

For example, *time* as a concept is uncountable.\
It would not make sense to say, for example:

*I’m sorry I haven’t got **a time** to talk to you now.*

However, *time* is countable when it means an occasion or a period.\
For example:

*I remember **a time** when 1 MB was a lot of memory.*\
*How many **times** have I asked you not to do that?*

Consider, too, the difference between:

*I don’t like **coffee**.*\
and\
*Would you like **a coffee**?*\
*How many **coffees** have you had this morning?*

## <a id="dangling-participles"></a>Dangling Participles

Participles are formed from verbs.

Present participles end in *-ing*; past participles often end in *-ed*, though there are many irregular forms. Some examples:

|                |                        |                     |
| -------------- | ---------------------- | ------------------- |
| **infinitive** | **present participle** | **past participle** |
| to bring       | bringing               | brought             |
| to have        | having                 | had                 |
| to lead        | leading                | led                 |
| to walk        | walking                | walked              |
| to write       | writing                | written             |

Participles are often used as convenient concise forms. For example:

**Being** the project leader, Hannah Jones chaired the meeting. \[A more concise form of: *As she is the project leader, Hannah Jones chaired the meeting.*]

I was given a spec **written** on the back of an envelope. \[An alternative form of: *I was given a spec that was written on the back of an envelope.*]

**Having** caught a terrible cold, I phoned my colleagues to postpone the meeting. \[In other words: *As I had caught a terrible cold, I postponed the meeting.*]

Participles can work well when used in this way, but we need to be careful that our sentence is unambiguous. Consider the last example again:

Having caught a terrible cold, I phoned my colleagues to postpone the meeting.

Who had caught the cold? Was it me or was it my colleagues? Clearly, it was me, but how do we know this? We know because **we assume that the next noun phrase after the participle clause denotes the person or thing that the participle refers to**.

Look at these similar sentences:

Being corrupt, the file was rejected. \[Since the next noun phrase after the participle phrase is *the file*, it’s clear that it’s the file that’s corrupt.]

Being corrupt, I rejected the file. \[In this case, basing our understanding purely on the word order, we might interpret this to mean that I am the one who is corrupt.]

Usually with such poorly chosen word order, we can probably guess at the intended meaning. However, our goal is that our readers should correctly interpret our material on the first reading.

When the structure of the sentence leaves it unclear to whom or what the participle refers, this is called a "dangling" or "unrelated" participle.

Here are some other examples of poorly chosen, and hence distracting, word order, with some suggestions for improvement:

|                                                                               |                                                                              |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **"Dangling participle" version**                                             | **Improved version**                                                         |
| **Being** a public holiday, the office was closed.                            | As it was a public holiday, the office was closed.                           |
| **Having** crashed three times in one week, we decided to replace the server. | As the server had crashed three times in one week, we decided to replace it. |

<!-- vale Vaadin.HeadingCase = NO -->

## <a id="definite-article-the"></a>Definite Article (“the”)

<!-- vale Vaadin.HeadingCase = YES -->

## <a id="indefinite-article"></a>Indefinite Article

See ["a" / "an"](https://vaadin.com/docs/v23/contributing-docs/style-guide/word-list.md#word-list.a_an)

## <a id="introduction"></a>Introduction

## <a id="grammar.nouns_as_descriptors"></a>Nouns as Descriptors

English is very versatile in allowing nouns to be used as if they were adjectives. For example:

<!-- vale Vaadin.Please = NO -->

Please close the **office** door quietly.

Select your preferred **keyboard** layout.

<!-- vale Vaadin.Please = YES -->

Bear in mind that when nouns are used like adjectives in this way, they are almost always used in the singular form, not plural. For example:

She is the manager of a **shoe** shop. \[Not *a shoes shop*.]

This is the responsibility of the **microchip** manufacturer. \[Not *the microchips manufacturer*.]

## <a id="passive-voice"></a>Passive Voice

Grammatically speaking, there are two kinds of voice: *active voice* and *passive voice*.

An *active* sentence generally follows the standard *subject – verb – object* format.\
For example:

*The dog bit the man.*

In an *active* sentence such as this, the subject of the verb (*the dog*) is also the *agent* (the person or thing that *performs* the verb).

By contrast, in a *passive* sentence, the subject of the verb is **not** the *agent*; that is, it isn’t the person or thing that performs the verb.

The man was bitten by the dog.

In this sentence, the subject of the verb is now *the man*; but the *agent* is still the dog.\
In a *passive* sentence, the *agent* is denoted using the preposition *by*.\
Specifying the *agent* is grammatically optional; that is, we may choose not to do it.\
For example:

The man was bitten.

We use the passive voice for three common reasons:

- to place emphasis on a different part of the sentence

- because we don’t know who or what the agent is

- because it’s unimportant who or what the agent is.

The *passive voice* is often useful and appropriate.\
For example:

*English is spoken all over the world.*

To express this as an active sentence, we would have to say

*They (or 'people') speak English all over the world.*

Unfortunately, this may lead us to wonder who *they* (or *people*) are, even though in this case it’s unimportant.\
For this reason, the *passive* version is preferable here.

However, in terms of style, using the *passive* too much can have the effect of making our language sound excessively formal.

<!-- vale Vaadin.JustSimply = NO -->

Accordingly, avoid using the *passive* when it’s possible to express the same idea elegantly and simply in *active voice*.

<!-- vale Vaadin.JustSimply = YES -->

## <a id="phrasal-verbs"></a>Phrasal Verbs

## <a id="grammar.relative_clauses"></a>Relative Clauses

Relative clauses allow us to give more information about a person or thing that we mention in a sentence. For example:

**Instead of saying:** *I asked Linda Johnson. She works in the same office as me*,

**it’s neater to say:** *I asked Linda Johnson, who works in the same office as me*.

They are called "relative clauses" because they relate to some entity in the main clause of our sentence. The word that links the relative clause to the main clause is often a "W" word, such as *which*, *who*, *where*, *when*, or *whose*. The word *that* is also often used as the linking word. For example:

The software is written in Java, which is our preferred language.

<!-- vale Vale.Spelling = NO -->

Jean Reboulet, who led the design team, attended the meeting.

<!-- vale Vale.Spelling = YES -->

The conference was held in San Francisco, where the company has its headquarters.

We recommend performing full backups at the weekend, when the system is less busy.

We contacted Sandra Stein, whose team maintains the library.

This is the team that maintains the library.

We need to be aware that there are two kinds of relative clause: **defining** and **non-defining**.

Why is this important? It matters because it has an impact on the punctuation we need to use, and also on the sentence structure.

A **defining relative clause**, as the name suggests, defines an entity in the main clause. It gives us essential information to identify the person or thing that was mentioned. In other words, without the information in this clause, our sentence would not have the same meaning and might not even make sense at all. For example:

This is the bug **which our testing team reported**.\
\[The relative clause is essential to understand which bug is being talked about.]

The place **where you parked your car** is private property.\
\[The relative clause identifies the place that was mentioned.]

## <a id="split-infinitive"></a>Split Infinitive

The infinitive of a verb is the form that includes the particle "to". Examples of infinitives are *to have*, *to hold*, and *to program*.

Traditionally, it was considered bad style to "split" the infinitive by placing an adverb between the particle and the verb. For example:

It’s necessary to **fully** understand the process before starting. \[Instead of, for example, *to understand the process fully*.]

We had to **completely** rebuild the library. \[Instead of, for example, *to rebuild the library completely*.]

Although split infinitives are generally considered to be acceptable these days, it’s worth considering whether you could easily write your sentence to avoid it.

However, there may be some cases where strictly imposing the ideal of avoiding split infinitives could result in an awkward sentence or even introduce ambiguity. Clearly, we need to prioritize simplicity, clarity, and accuracy always, even if it means we have to compromise on elegance.

## <a id="grammar.time_clauses_in_future"></a>Time Clauses in the Future

We often use time clauses to refer to some time in the future. Such clauses may begin with *when*, *while*, *until*, *as soon as*, *before*, and *after*. In English, we generally use a present or present perfect tense in this type of clause, although it refers to a future time. The rest of the sentence may use any appropriate future form, or an imperative (instruction) form. For example:

<!-- vale Vaadin.Will = NO -->

As soon as you **get** to the office, call me. \[Not *As soon as you will get…*]

While I **am** in Scotland, I’ll visit Edinburgh Castle. \[Not *While I will be in Scotland…*]

When you **have finished** that work, you can start the next task. \[Not *When you will finish…* or *When you will have finished…*]

<!-- vale Vaadin.Will = YES -->

`8BD95586-0E8D-4D5A-99B9-583629D4750D`
