109 lines
3.8 KiB
Plaintext
109 lines
3.8 KiB
Plaintext
= Styling Guide
|
|
|
|
This document provides styling guidelines for `+rule.adoc+` and its dependencies.
|
|
|
|
|
|
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.
|
|
|
|
== Code
|
|
|
|
Only use inline literals (backtick) for direct code references, for instance, variable names or values. Inline literals should not be used for anything else.
|
|
|
|
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.
|
|
|