-
Notifications
You must be signed in to change notification settings - Fork 35
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
dlavender4
wants to merge
6
commits into
main
Choose a base branch
from
sonarqube_changes
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
947c780
sonarqube benefits of default rules, and making best practices clearer
dlavender4 809da88
Merge branch 'master' into sonarqube_changes
iw-ezequiel 435b586
Merge branch 'master' into sonarqube_changes
andyblundell 0d477db
Merge branch 'master' into sonarqube_changes
andyblundell d82b528
Merge branch 'main' into sonarqube_changes
andyblundell 9abe36c
Merge branch 'main' into sonarqube_changes
dlavender4 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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)). | ||
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. | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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?