A RetroSearch Logo

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Search Query:

Showing content from https://docs.sonarsource.com/sonarqube-server/latest/extension-guide/adding-coding-rules/ below:

Adding coding rules | SonarQube Server Documentation

There are three ways to add coding rules to SonarQube Server:

The Java API will be more fully-featured than what's available for XPath, and is generally preferable. However, this comes with the overhead of maintaining a SonarQube Server plugin (including keeping it up-to-date as APIs change, upgrading the plugin after releasing a new version).

Importing generic issue reports is a good solution when there's a very specific need for a subset of projects on your SonarQube Server instance. They are the most flexible option but lack some features (such as being able to control their execution by inclusion in a quality profile).

Before implementing a new coding rule, you should consider whether it is specific to your own context or might benefit others. If it might benefit others, you can propose it on the community forum . If there is a shared interest, then it might be implemented for you directly in the related language plugin. It means less maintenance for you and benefit to others.

Custom rule support by language Adding coding rules using Java

Writing coding rules in Java is a six-step process:

  1. Create a SonarQube Server plugin.
  2. Put a dependency on the API of the language plugin for which you are writing coding rules.
  3. Create as many custom rules as required.
  4. Generate the SonarQube Server plugin (jar file).
  5. Place this jar file in the <sonarqubeHome>/extensions/plugins directory.
  6. Restart SonarQube Server.

See the following pages to see samples and details about how to create coding rules

Notes: 

Adding coding rules using XPATH

SonarQube Server provides a quick and easy way to add new coding rules directly via the web interface for certain languages using XPath 1.0 expressions. For XML, which is already immediately accessible to XPath, you can simply write your rules and check them using any of the freely available tools  for examining XPath on XML. If you're writing rules for XML, skip down to the Adding your rule to the server section once you've got your rules written.

For other languages how to access a variable, for example, in XPath is less obvious, so we've provided tools.

Writing an XPath rule using SSLR toolkit

The rules must be written in XPath (version 1.0) to navigate the language's abstract syntax tree  (AST). For most languages, an SSLR Toolkit is provided to help you navigate the AST. You need to download the sslr-{language}-toolkit-{version}.jar file corresponding to the version of your language plugin you have on your SonarQube Server instance.

Each language's SSLR Toolkit is a standalone application that displays the AST for a piece of code source that you feed into it, allowing you to read the node names and attributes from your code sample and write your XPath expression. Knowing the XPath language is the only prerequisite, and there are a lot of tutorials on XPath online.

The latest version of SSLR Toolkit can be downloaded from the following locations:

For an SSLR preview, consider the following source code sample:

function HelloWorld(hour) {
  if (hour) {
    this.hour = hour;
  } else {
    var date = new Date();
    this.hour = date.getHours();
  }
  this.displayGreeting = function() {
    if (this.hour >= 22 || this.hour <= 5)
      document.write("Good night, World!");
    else
      document.write("Hello, World!");
  } 
}

While parsing source code, SonarQube Server builds an abstract syntax tree (AST) for it, and the SSLR toolkit provided for each language will show you SonarQube Server's AST for a given piece of code. Here's the AST for our sample:

The XPath  language provides a way to write coding rules by navigating this AST, and the SSLR toolkit for the language will give you the ability to test your new rules against your sample code.

Adding your Rule to SonarQube Server

Once your new rule is written, you can add it to SonarQube Server:

  1. Log in as a quality profile administrator.
  2. Go to the Rules page.
  3. Select the language for which you want to create the XPath rule.
  4. Tick the Template criterion and select Show Templates Only.
  5. Look for the XPath rule template.
  6. Click on it to select it, then use the interface controls to create a new instance.
  7. Fill in the form that pops up.
  8. Once you've created your rule, you'll need to add it to a quality profile and run an analysis to see it in action.
Coding rule guidelines

These are the guidelines that SonarSource uses internally to specify new rules. Rules in community plugins are not required to adhere to these guidelines. They are provided here only in case they are useful.

Note that fields "title", "description" and "message" have a different format when the rule type is "hotspot".

Guidelines applicable to all rules Code examples

Do not give examples that make references to real companies or organizations:

$fp = file_get_contents("https://www.real-company.com");

Should be replaced by a neutral website:

$fp = file_get_contents("https//www.example.com");
// or even better:
$fp = file_get_contents("https://localhost");
See/References

When a reference is made to the specification of a standard, e.g. MISRA, the following steps must also be taken:

If needed, references to other rules should be listed under a "see also" heading. If a "see" heading exists in the rule, then the "see also" title should be at the h3 level. Otherwise, use an h2 for it.

Other rules should be linked to only if they are related or contradictory (such as a pair of rules about where { should go).

Why list references to other rules under "see also" instead of "see"? The "see" section is used to support the current rule, and one rule cannot be used as justification for another rule.

Classifying your rules

Now that you've fleshed out the description, you should have a fairly clear idea of what software qualities this rule impacts, but to be explicit:

Reliability: Something that's wrong or potentially wrong.

Maintainability: Something that will confuse a maintainer or cause them to stumble in their reading of the code.

Security: Something that's wrong which impacts the application's security and therefore needs a fix.

Hotspot: An optional protection is missing and the developer needs to do a review before deciding whether to apply a fix.

Sometimes the line between reliability and maintainability is fuzzy. When in doubt, ask yourself: "Is code that breaks this rule doing what the programmer probably intended?" If the answer is "probably not" then it's a reliability issue. Everything else is a maintainability issue.

The main differences between a security impact and hotspots are explained on the Security hotspots page. During the specification of a rule, the following guidelines might also help:

The difficulty of exploiting a weakness should not be a criterion for specifying a hotspot or a security impact.

Security impacts and hotspots should not overlap but can be related to the same subject. For example, with the hotspot RSPEC-2077, formatted SQL queries are highlighted and we recommend the use of prepare statements as additional protection to prevent SQL-injection vulnerabilities (RSPEC-3649).

Now that you've fleshed out the description, you should have a fairly clear idea of what type of rule this is, but to be explicit:

Bug: Something that's wrong or potentially wrong.

Code Smell: Something that will confuse a maintainer or cause them to stumble in their reading of the code.

Vulnerability: Something that's wrong which impacts the application's security and therefore needs a fix.

Hotspot: An optional protection is missing and the developer needs to do a review before deciding whether to apply a fix.

Sometimes the line between bug and code smell is fuzzy. When in doubt, ask yourself: "Is code that breaks this rule doing what the programmer probably intended?" If the answer is "probably not" then it's a bug. Everything else is a code smell.

The main differences between vulnerabilities and hotspots are explained on the Security hotspots page. During the specification of a rule, the following guidelines might also help:

Default severities

When assessing the default severity of a rule, the first thing to do is ask yourself "what's the worst thing that could happen?" In answering, you should factor in Murphy's Law without predicting Armageddon.

Once you have your answer, it's time to assess whether the impact and likelihood of the worst thing are high or low. To do that, ask yourself these specific questions:

Security

Reliability

Maintainability

Once you have your impact and likelihood assessments, the rest is easy:

impact likelihood Blocker Y Y High Y N Medium N Y Low N N

Vulnerability

Bug

Code Smell

Once you have your impact and likelihood assessments, the rest is easy:

impact likelihood Blocker Y Y Critical Y N Major N Y Minor N N Tags

Rules can have 0-n tags, although most rules should have at least one. Many of the common-across-languages tags are described in the rules docs.

Evaluation of the remediation cost

For most rules, the SQALE remediation cost is constant per issue. The goal of this section is to help define the value of this constant and to unify the way those estimations are done to prevent having some big discrepancies among language plugins.

First, classify the effort to do the remediation:

Then use the following table to get the remediation cost according to the required remediation effort and to the language:

Trivial Easy Medium Major High Complex ABAP, COBOL, ... 10min 20min 30min 1h 3h 1d Other languages 5min 10min 20min 1h 3h 1d

For rules using either the "linear" or "linear with offset" remediation functions, the "Effort To Fix" field must be fed on each issue and this field is used to compute the remediation cost.

Issue location(s) and highlighting

For any given rule, highlighting behavior should be consistent across languages within the bounds of what's relevant for each language.

When possible, each issue should be raised on the line of code that needs correction, with highlighting limited to the portion of the line to be corrected. For example:

When correcting an issue requires action across multiple lines, the issue should be raised on the lowest block that encloses all relevant lines. For example an issue for:

When an issue could be made clearer by highlighting multiple code segments, such as a method complexity issue, additional issue locations may be highlighted, and additional messages may optionally be logged for those locations. In general, these guidelines should be followed for secondary issue locations:

Guidelines when writing rules for issues Titles

Noncompliant title examples:

Compliant solutions:

Starting with the subject, such as "Files", will ensure that all rules applying to files will be grouped together.

Descriptions

Rule descriptions should contain the following sections in the listed order:

Code samples for COBOL should be in upper case.

When displayed in SonarQube Server, any code or keywords in the description should be enclosed in <code> tags. For descriptions written in JIRA, this means using double curly braces ({{ and }}) to enclose such text. They will be translated in the final output.

Messages

Issue messages should contain the remediation message for bug and quality rules. For potential-bug rules, it should make it explicit that a manual review is required. It should be in the imperative mood ("Do x"), and therefore start with a verb.

An issue message should always end with a period ('.') since it is an actual sentence unless it ends with a regular expression, in which case the regular expression should be preceded by a colon and should end the message.

Any piece of code in the rule message should be double-quoted (and not single-quoted). Moreover, if an issue is triggered because a number was above a threshold value, then both the number and the threshold value should be mentioned in the issue message.

Sample messages:

Sample Specification Generic exceptions should not be thrown

Using generic exceptions such as Error, RuntimeException, Throwable, and Exception prevents calling methods from handling true, system-generated exceptions differently than application-generated errors.

Noncompliant Code Example

With the default regular expression [a-z][a-zA-Z0-9]+:

try { /* ... */ } catch (Exception e) { LOGGER.info("context"); } // Noncompliant; exception is lost
try { /* ... */ } catch (Exception e) { LOGGER.info(e); } // Noncompliant; context is required
try { /* ... */ } catch (Exception e) { LOGGER.info(e.getMessage()); } // Noncompliant; exception is lost (only message is preserved)
try {
/* ... */
} catch (Exception e) { // Noncompliant - exception is lost
throw new RuntimeException("context");
}

Compliant Solution

try { /* ... */ } catch (Exception e) { LOGGER.info("context", e); }
try {
/* ... */
} catch (Exception e) {
throw new RuntimeException("context", e);
}

Exceptions
Generic exceptions in the signatures of overriding methods are ignored.

@Override
public void myMethod() throws Exception {...}

See

See also
S4567 - Rule title here

Guidelines for Hotspot rules

See RSPEC-6502  for an example of a Hotspot rule.

Titles

Noncompliant Title Examples:

Compliant Solution:

Descriptions

Rule descriptions should contain the following sections in the listed order:

Guidelines regarding COBOL, keywords, and code are the same as for other rules.

Messages

Most of the time you can paraphrase the title:

Examples:

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4