See also the <<styling_guide.adoc#,Styling Guidelines>>, <<tone_guide.adoc#,Tone Guide>> and https://docs.sonarqube.org/latest/extension-guide/adding-coding-rules/#coding-rule-guidelines[Coding rule guidelines].
// This needs to be kept in sync with the [maps in the validation script](https://github.com/SonarSource/rspec/blob/master/rspec-tools/rspec_tools/validation/description.py#L32-L39).
Where the `How to fix it in {Framework Display Name}` section can be repeated multiple times when the rule description is defined per-framework.
The sections and subsections for this format are defined as follows:
* Short description (no title) [Optional]
+
A short introduction/summary of the topic, only a few sentences. +
Goal: The title (or message) of a rule might not always be clear due to its shortness, and this should make it clear to our users what the issue is about. Experienced developers will immediately understand what it is about, and developers not yet familiar with the issue at hand can dig deeper into the `Why is this an issue?` section.
Start at the basics and go into more depth to explain the concepts behind this type of issue. This is most likely the place where a lot of the content will be. +
This is the place to tell the “story” of the rule, including the impact of leaving it unfixed. We should include code samples wherever needed to make it easier to understand
what is going on. This can be in the form of noncompliant and compliant code in a single code box (noncompliant lines should always be highlighted with the corresponding comment
“// Noncompliant” optionally followed by some explanation) if that is clearer. This first tab could use a blog post style with a free format explaining what the rule is
This subsection aims to address questions such as the following: +
What is the risk for me? What is the risk for my organization? What is the risk for the users? What can go wrong? +
This section aims to talk about the impacts on the software, depending on the code qualities this issue is linked to: security, reliability, or maintainability. **(see <<metadata.adoc#code-field,Impacts>>.)**
+
Consequently, this section can also talk about the impacts on the ecosystem of this software. For example, impacts on the organization, on the users, and impact in terms of regulations.
* *How to fix it* or *How to fix it in `{Framework Display Name}`* (level 2 title) [Optional; the title depends on whether the description is generic or framework-specifc. See examples below.]
This section consists of one or multiple fixes for this type of issue (`Noncompliant code example` vs. `Compliant solution`). There can be multiple fixes for different libraries and/or frameworks.
If the fix for the rule is trivial (quickfix is available, it is easily inferred from the title and/or message), this section should be omitted and the fix could be mentioned in the previous section. +
Goal: Get an idea of how this issue can be fixed for my project/framework, why this works, what to look out for, and also how to continue improving on this topic.
This section lists Sonar rules related to the current one. The rule ID(s) should be followed by the rule title(s) or a sentence explaining the relation between the rules, e.g.: "_S2275 and S3457 specialize in detecting type mismatches with format strings._".
Note that you can see two special attributes (`diff-id` and `diff-type`) used in the code examples above, these attributes are explained in the <<Diff view,Diff view>>
section below.
When the content is framework-specific, one or more "_How to fix it in `{Framework Display Name}`_" sections (with their respective subsections) must be present.
Each repetition will represent the specific _How to fix it_ section of a given framework.
Most sections and subsections of the Learn as You Code rule format are optional, only the `Why is this an issue?` main section is mandatory.
The goal is to provide the right level of guidance so that users get the right information from the rules at the right time.
Do not feel obliged to use every section or sub-section if omitting them would lead to a better user experience.
==== Guidelines if you aren’t sure where something belongs in a rule
* If you need the information to fix the issue, but only the first time, it probably belongs in ‘Why is this an issue?’
* If you need the information to fix the issue every time, it probably belongs in ‘How to fix it?’
* If you don’t need the information to fix the issue, but it will help users grow their knowledge, it probably belongs in ‘Resources’ (this maps to the 'More Info' tab in the products)
By being careful about what goes where, we help to ensure that users get exactly what they need, when they need it.
==== Guidelines on content focus
We want to help users to create Clean Code. Rule content should focus on the manner in which the code is not clean, why this is an issue, and how to remedy this.
Rules should talk about the potential impact on software quality in the 'What is the potential impact?' sub-section.
For example, if you are talking about a locking issue, it makes sense to focus on the logical issues that could lead to a deadlock and how to fix that in the main rule content.
The implications of a deadlock on the application reliability would then go into the 'What is the potential impact?' sub-section.
Parameters should be listed in a subsection as follow:
....
=== Parameters
.name
****
_TYPE_
----
default value
----
Description of what the parameter does.
****
.name2
****
----
another default value
----
Description of what this second parameter does.
****
.name3
****
_TYPE_
Description of what this third parameter does.
****
.name4
****
Description of what this fourth parameter does.
****
....
The parameter name and the description are mandatory. The type and default value are not.
The parameter name with a `.` before will be the title of the block below marked by `****`.
We always use `----` around the default parameter to avoid having a special character confuse AsciiDoctor and to create a visual consistency for all parameters.
== Comment a rule
Comments and links that were created on Jira have been gathered in a `comments-and-links.adoc` file for each concerned rule. +
You can add a comment anywhere in a rule by adding the following lines in the `*.adoc` file:
[source]
----
\ifdef::env-github,rspecator-view[]
John Doe (9 Jun 2021, 15:49): my comment on the rule
\endif::env-github,rspecator-view[]
----
This way, your comment will only be visible in GitHub preview and on the Search Page (and will not be visible for the user).
