Skip to content

Latest commit

 

History

History
125 lines (81 loc) · 4.62 KB

styling_guide.adoc

File metadata and controls

125 lines (81 loc) · 4.62 KB
Raw

Styling Guide

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

See also the Description Guidelines for information about the rule structure and the 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.

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