Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

sonarqube benefits of default rules, and making best practices clearer #211

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 34 additions & 46 deletions tools/sonarqube.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
# Sonarqube
# SonarQube

SonarQube® is an automatic code review tool to detect bugs, vulnerabilities, and code smells in your code. It can integrate with your existing workflow to enable continuous code inspection across your project branches and pull requests.

## Benefits of SonarQube

SonarQube gives you the tools you need to write clean and safe code:

- SonarLint – SonarLint is a companion product that works in your editor giving immediate feedback so you can catch and fix issues before they get to the repository.
@@ -11,68 +13,52 @@ SonarQube gives you the tools you need to write clean and safe code:
- Security Hotspots – SonarQube highlights security-sensitive pieces of code that need to be reviewed. Upon review, you'll either find there is no threat or you need to apply a fix to secure the code.
- Raises "smells". It knows _something_ looks odd, and suggests a fix (only suggests!). Your team can then look at the bigger picture around that code, and fix the smells in whichever way is best.
- Dependency vulnerability scanning - provided by the [dependency-check-maven plugin](dependency-check-maven/README.md)
- Many other available plugins

# Profile
Quality Profiles are a core component of SonarQube, since they are where you define sets of Rules that - when violated - should raise issues on your codebase (example: Methods should not have a Cognitive Complexity higher than 15). Quality Profiles are defined for individual languages.

While it's recommended to have as few Quality Profiles as possible to ensure consistency across projects, you can define as many Quality Profiles as are necessary to fit your specific needs.
## Best Practices for using SonarQube

The "Sonar Way" Quality Profiles are a good starting-point as you begin analysing code, and they start out as the default Quality Profiles for each language, created by knowledge experts.
1. Use the default SonarQube rulesets\
For most languages / frameworks, SonarQube provides out-of-the-box default rulesets. The benefit is that these are automatically patched whenever SonarQube is: new rules are added over time, out-dated rules are removed. They constantly represent best-practices for that language.
If you create your own rulesets, they will not be automatically updated.

# Rules
SonarQube executes rules on source code to generate issues. There are four types of rules:
2. Use the SonarWay default Quality Gates\
As above, these are auto-updated by SonarQube over time.
At time of writing, the current conditions are:

- Code Smell (Maintainability domain)
- Bug (Reliability domain)
- Vulnerability (Security domain)
- Security Hotspot (Security domain)
| Metric | Operator | Value |
| ------ | -------- | ----- |
| Coverage | is less than | 80.0% |
|Duplicated Lines (%)|is greater than|3.0%
|Maintainability Rating|is worse than|A
|Reliability Rating|is worse than|A
|Security Hotspots Reviewed|is less than|100%
|Security Rating|is worse than|A

# Quality Gate
Quality Gates enforce a quality policy in your organisation by answering one question: is my project ready for release?

To answer this question, you define a set of conditions against which projects are measured. For example "No new blocker issues", "Code coverage on new code greater than X%".

We recommend that you define one gate for [new code](#definition-of-new-code), and another that covers **all** code (new and legacy).
3. For legacy code, use two sets of gateways\
If working with legacy software, you might need to create two sets of gateways and rulesets. One for new code ("The entire contents of any file that was changed as part of this commit."), and another that covers **all** code (new and legacy).
This approach facilitates getting new code right, without having to instantly fix legacy code.

## Definition of new code
New code is defined by SonarQube as:
The entire contents of any file that was changed as part of this commit.

## Default quality gates
By default, SonarQube provides a basic quality gate called the Sonarqube Way, with the following failure conditions.
## Configuring CI pipeline

Conditions on New Code:
Making SonarQube part of a Continuous Integration process is recommended: a build should fail if the code analysis did not satisfy the Quality Gate condition (see [Quality Checks](../quality-checks.md)).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps reference dashboards as a very compelling reason to do this?

Bear in mind that SonarQube analyses projects asyncronously. So your build will need to wait for SonarQube to finish. SonarQube provides a REST API that you can poll to see whether analysis has finished, and to obtain the final result.

| Metric | Operator | Value |
| ------ | -------- | ----- |
| Coverage | is less than | 80.0% |
|Duplicated Lines (%)|is greater than|3.0%
|Maintainability Rating|is worse than|A
|Reliability Rating|is worse than|A
|Security Hotspots Reviewed|is less than|100%
|Security Rating|is worse than|A
## FAQs

NB: These are subject to change as Sonarqube is updated
### SonarQube is going to add weeks to my workload

The recommendation is that we use the Sonarqube Way for all projects. Teams will eventually diverge, but these diversions need to be closely monitored by the Tech Lead and the team.

# Configuring CI pipeline
Making SonarQube part of a Continuous Integration process is recommended: a build should fail if the code analysis did not satisfy the Quality Gate condition (see [Quality Checks](../quality-checks.md))

# FAQs

## SonarQube is going to add weeks to my workload!
Initially, yes, it might. Going forwards though, we should see fewer things being picked up by SonarQube. This is because these coding standards will become embedded in the team's heads: encouraging best practices before they've written a line of code.
SonarQube can then also act as a guide for new people joining: this is how we write code: these are our standards.
Also remember that, for legacy code, you can use a separate gateway to allow lower standards while you gradually bring that legacy code up to scratch. You can also use refactoring techniques to - for example - extract functionality from troublesome classes and put it somewhere else that can easily be refactored.

## Why should I listen to SonarQube?
### Why should I listen to SonarQube?

You live and breathe your code every day: you're probably aware of every pitfall and quirk.
New starters won't be.
New starters won't be.
You've probably also got used to the fact that code changes take X times longer than they could, because the code is not as maintainable as it could be.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or, perhaps you've become comfortable with workarounds that are second nature after executing them so many times, and a crude view provided by an external tool serves as a reminder of potential improvements.

## The suggested fix is nonsense!
### The suggested fix is nonsense!

SonarQube does two jobs: finds real issues; and raises "smells".
Smells only give you _suggested fixes_. You do not have to follow its suggestions. But you do have to make the build pass again!
For example: SonarQube raises 10 smells in a piece of code: tiny, annoying things. It isn't telling you to fix them. You could. And get the build passing again like that - but that's not the point.
@@ -81,6 +67,8 @@ What's _really_ causing those underlying issues?

The idea of SonarQube isn't to unquestioningly implement every individual suggested code change, just to get the build to pass. Instead, we should use these suggestions, especially where we have a concentration of suggestions in one area of the code, to consider if there is something bigger that we need to address to improve our code.

## Why these rules?
### Why these rules?

The default sonar rules are established industry standards, crafted by experts, and a really good place to start.
If all teams use them, it will breed familiarity across individuals and teams.
They are also updated by SonarQube releases, which means they won't get "stale" as new language versions are released, or as industry best-practices change over time.