126 lines
4.6 KiB
Plaintext
126 lines
4.6 KiB
Plaintext
= 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
|
|
----
|