= Styling Guide

This document provides styling guidelines for `+rule.adoc+` and its dependencies.

See also the <<description.adoc#,Description Guidelines>> for information about the rule structure and the <<tone_guide.adoc#,Tone Guide>> for guidance on the tone of voice to use.


The RSPEC styling guide is loosely based on the Associated Press Style and geared to rule descriptions.
The official Associated Press Style should be used as a fall-back for topics not defined here.
The guide might be extended in the future when unanimities emerge.


Following it should be considered a goal to work towards to get more homogenous texts.
This will be a long process consisting of many baby steps, such as adjusting the style when rule descriptions are rewritten for the Progressive Education Framework.
It is acceptable not to have 100% consistency across all texts. The higher the consistency, the better, but differences are expected.

== Language

Use _American English_ and its notation.

== Acronyms

Do not use acronyms without defining them first unless they are considered well known by the target audience.
For example, the acronym _JDK_ can be considered common knowledge for a Java developer and does not have to be defined.
The definition of what is and is not a well-known acronym is somewhat subjective.
It is up to the reviewers of RSPEC pull requests to challenge the use of acronyms that might not be well known.

If possible and sensible, spell out the acronym on first use and use generic terms on subsequent mentions.
For example, refer to _Cross-Site Scripting_ as _the vulnerability_.

Write:: Cross-Site Scripting allows to inject JavaScript code in the context of a website. The vulnerability can be abused to hijack sessions.
Avoid:: XSS allows to inject JS code in the context of a website. XSS can be abused to hijack sessions.

== Contractions

Contractions are considered informal writing and therefore should not be used.

Write:: It is the right way!
Avoid:: It's not the right way!

== Numbers

In general, spell out numbers one through nine. Use digits for numbers 10 and higher.
Be aware that there are many exceptions to this rule. For instance, use digits for units or percentages.

Write:: 5°C is 9% warmer than yesterday. The condition checks if the value is greater than eight and smaller than 100.
Avoid:: The condition checks if the value is greater than 8 and smaller than one hundred.


Commas should be used to group three digits of numbers larger than 999.

Write:: My program creates 1,000,000 forks.
Avoid:: My program creates 1000000 forks.

== Punctuation

=== Colon

Do not capitalize the first word after a colon unless it is the start of a sentence or a proper noun.

Write:: There is only one thing we can do: rewrite.
Avoid:: There is only one thing we can do: Rewrite.

=== Comma

To avoid ambiguity, add the Oxford comma after the penultimate term in a series of three or more terms.

Write:: My code is slick and works. My code is not slow, unreliable, and full of bugs.
Avoid:: My code is slick, and works. My code is not slow, unreliable and full of bugs.

=== Parentheses

Parentheses should be avoided. If the information is relevant, it is preferred to incorporate it directly in a sentence.

Write:: This is a test that forms an example.
Avoid:: This is a test (example).

== Lists

Do not capitalize the first word of list entries unless it is the start of a sentence or a proper noun.

Write::
Check the values:
 * size
 * length

Avoid::
Check the values:
 * Size
 * Length

Do not add punctuation for enumerations.

Write::
Check the values:
 * size
 * length

Avoid::
Check the values:
 * size,
 * length.

== Literals

Inline literals (backticks) should be used to highlight short values.
Use it when referencing variable names, file names, tokens, and all kinds of specific strings of text that should be visually extracted from the surrounding default text.

Write:: Compiling source file `src/generic_file.py` breaks an `assert` call in pytest framework.
Avoid:: Compiling source file "src/generic_file.py" breaks an `assert` call in `pytest` framework.

== Referencing elements from the code

When referencing elements from the code within a normal sentence, use the `backticks` (```) to format it. This includes variable names, function names, class names, and so on.

When referencing the same elements within a comment in a code block, surrpond it with double quotes.
[source,cpp]
----
int i = 0;
// Write
cout << noexcept(++i); // Noncompliant, "i" is not incremented -> Double quotes
// Avoid
cout << noexcept(++i); // Noncompliant, i is not incremented -> No quotes
cout << noexcept(++i); // Noncompliant, `i` is not incremented -> Backticks
----
