Technical Debt Evaluation (SQALE)
Installation and Usage
Installing the SQALE Plugin
The SQALE plugin does not have any specific requirements beyond what is required for the SonarQube platform.
- Copy the file sonar-sqale-X.X.jar to SONARQUBE_HOME/extensions/plugins or use the Update Center to install the latest version.
- Restart the SonarQube server.
- Log in as a System administrator, go to Settings > General Settings > Licenses, paste your license key and Save (was Configuration > General Settings > SQALE prior to version 1.9).
- Restart the SonarQube server again.
Computing SQALE Technical Debt
The SonarSource implementation of the SQALE methodology is based on SonarQube’s rules and issues. Each time a new issue is encountered, additional technical debt – the time to fix the issue – is accrued. The time required to fix an issue of each rule is obviously different, and fully customizable (see “Customizing the Analysis Model” below). However you may not need to because, SonarSource’s team of experienced programmers has set these remediation cost estimates to very sane defaults.
To compute the SQALE technical debt, just run an analysis of your project. The results will be based on the issues that are found in the code. Since, the SonarQube implementation of SQALE is based solely on rules and issues, if you want to manage all your technical debt with SQALE, you’ll first need to enable the rules in the Common SonarQube repository that flag:
- Duplicated blocks
- Failed unit tests
- Insufficient branch coverage by unit tests
- Insufficient comment density
- Insufficient line coverage by unit tests
- Skipped unit tests
The SQALE model computes an application’s technical debt based on rules and remediation costs. Once the debt is calculated, each application gets a health rating based on its density of technical debt, which is basically the effort to fix it versus the effort that has already gone into it.
The SQALE density formula is:
Remediation cost / Development cost
Which can be restated as:
Remediation cost / (Cost to develop 1 line of code x Number of lines of code)
Remediation cost / (Cost to develop 1 point of complexity x Complexity)
depending on the size metric that is chosen.
For an application with:
- Size: 2,500 lines of code
- Total remediation cost: 50 days
And given that the cost to develop one line of code is estimated at 0.06 days, that works out to
50/(0.06 * 2,500) = 0.33
The default SQALE rating axis is:
A=0-0.1, B=0.11-0.2, C=0.21-0.5, D=0.51-1
So according to the rating grid, the SQALE rating of the application would be a C.
The SQALE rating scale can be alternately stated by saying that if the outstanding remediation cost is:
- <=10% of the time that has already gone into the application, the rating is A
- .11 to .2 the rating is a B
- .21 to .5 the rating is a C
- .51 to 1 the rating is a D
- anything over 1 is an E
Note that the SQALE rating scale and factors such as the time to develop a line of code are part of the SQALE Governance Model. As such, they are configurable, but only at a global level. It is not possible to tune these values at a project level.
Displaying SQALE Technical Debt Information
Like any other measures, the SQALE rating and the SQALE remediation cost can be used in the Measures Service and displayed in filters. For example, you can display all projects whose SQALE rating is less than C.
In addition, the SQALE plugin comes with six dashboard widgets. Each widget gives you a slightly different insight into your technical debt, and you can drill down from most of them.
SQALE Overview Widget
The SQALE Overview widget offers an overview of your project’s quality, showing up to four metrics. Starting from the right, the Lines of Code metric is the size of the project in round numbers. In the middle is the technical debt in days. This value is the sum of the remediation costs for every open issue in the project. Both of these metrics are available from other widgets; it is the metrics on the left, the SQALE Rating and effort to reach an A rating, that are the stars of this show.
The SQALE rating scale has five values, from A to E, and it sums up the time to correct every issue in the application versus the effort that has already gone into coding the project. For more, see How SQALE ratings are determined.
SQALE Rating File Distribution Widget
The same way applications receive a SQALE rating, files do too, and the SQALE Rating File Distribution gives a visual indication of the distribution of files of each rating in your application.
SQALE Sunburst Widget
The SQALE Sunburst widget is another overview-style widget that also offers details. This configurable widget (you can choose how many of the three rings to show) shows the distribution of your technical debt. The inner ring shows the characteristics with outstanding technical debt; the middle ring is broken into sub-characteristics; and the outter ring, which offers a click-through to the Issues Drilldown, shows where your technical debt falls by rule.
Highest SQALE Remediaiton Costs Widget
Just as the SQALE Sunburst makes it easy to find the rule or sub-characteristic with the highest technical debt, the Highest SQALE remediation costs widget does the same thing for files. This Hotspot-style widget lists files by amount of technical debt – either across all characteristics or for the characteristic of the user’s choice (set via the dropdown in the widget’s upper-left.) The number of files to show is configurable, but defaults to five.
SQALE Remediation Costs to Reduce Risk Widget
The SQALE Remediation Costs presents your technical debt in the context of issue severity. This widget works from the top, down to show technical debt in a given severity versus the total cumulative debt. In the bar graph portion of the widget, the light blue portion of any bar represents the technical debt accrued in “this” severity. The dark blue portion of the bar is the cumulative total, again working from the top down. For instance, when you go from Major to Minor in the image above, the full width of the Major bar is the same as the dark blue portion of the Minor bar. The dark blue portion of Minor shows the technical debt accrued from Blocker, Critical, and Major, and then Minor picks up with light blue adding debt onto the end.
SQALE History Widget
The SQALE History widget shows how your application’s technical debt has changed over time. Each stratum represents a different characteristic, which the most important, or “foundational” characteristics on the bottom. Mouse over the strata, and the values for the date under the mouse will be overlayed onto the image and the date itself will appear in the upper-right, with the total technical debt at that time in the upper-left.
Technical Debt Pyramid Widget
The Technical Debt Pyramid widget doesn’t come with the SQALE plugin; it was moved into SonarQube core in version 4.0 as a fundamental piece of basic SQALE. It’s covered here for the sake of completeness.
While it certainly doesn’t look like an ancient Egyptian monument, this widget functions like one metaphorically. The way to read it is from the bottom up. Each row represents a characteristic, and each characteristic builds on the ones below it. Testability is at the bottom because it’s most important; it’s the foundation. So first you make sure your app is testable, then you make sure it’s reliable, then changeable, and efficient, and so on until you get to reusability at the top, which is a crowning piece.
As with the SQALE Remediation Costs to reduce risk widget, the bars in this graph show relative remediation time per characteristic, and the light blue and dark blue portions of the bars work the same way in both widgets.
Managing the SQALE Model
The SQALE Model is made up of two parts, both of which are fully editable through the SQALE plugin:
- SQALE Analysis Model – the coding rules/requirements and their remediation time estimates.
- SQALE Quality Model – the list of characteristics, the sub-characteristics in a characteristic, and the rules in a sub-characteristic.
Both parts of the SQALE Model rest foundationally on the rules. Rules are applied to projects through Quality Profiles. During an analysis every time an instance of a broken rule is encountered, an issue is raised against the project. Every issue increments the project’s technical debt by the rule’s remediation estimate.
Out of the box, the SQALE plugin provides a default configuration for the Quality model (i.e. a default list and ordering of characteristics and sub-characteristics.) Each language plugin then adds its own rules and remediation estimates to the Analysis model, and performs a default categorization of those rules into the sub-characteristics of the Quality Model.
Customizing the Quality Model
Go to Settings > SQALE and click on the “Quality Model” tab.
From there, you can:
- Add / Rename / Remove characteristics and sub-characteristics
- Order characteristics
Customizing the Analysis model
Go to Settings > SQALE and click on the “Analysis Model” tab.
For each rule/requirement, you can:
- Associate it with a sub-characteristic
- Define the function used to calculate the remediation cost of an issue generated from the rule. There are three options:
- Constant/issue – The cost to fix each issue from the rule is the same. For this rule, the total remediation cost per file = number of issues x constant
- Linear – The cost to fix an issue of this type depends on the magnitude of the issue. For instance, an issue related to file size might be linear, with the total cost-to-fix incrementing (by the coefficient amount) for each LOC above the allowed threshold.
- Linear with offset – It takes a certain amount of time to analyze an issue of this type (this is the offset). Then, the magnitude of the issue comes in to play. For instance, an issue related to complexity might be linear with offset. So the total cost to fix is the time to make the basic analysis (the offset) plus the time required to deal with each complexity point above the allowed value. Total remediation cost = offset + (number of noncompliance x coefficient).Linear and Linear with offset may only be used with rules that provide the Effort To Fix value.Let’s take as a example the “Paragraphs should not be too complex” rule. If you set the rule threshold to 20, and you have a paragraph with a complexity of 27, you have 7 points of complexity to remove. Internally, this is called the Effort to Fix. In that case, if you use the Linear with Offset configuration with an Offset of 4h and a Remediation Cost of 1mn, you will have a Technical Debt for this issue related to a too-complex block of code of: (7 complexity points x 1min) + 4h = 4h and 7mn
- See if you have changed the original definition of a requirement and reset it to its default value if required
Customizing Distribution Along the SQALE Rating Axis
The numbers behind the SQALE density formula (discussed in How SQALE ratings are determined) are configurable by going to Settings > General Settings > Technical Debt. Tuning the rating grid allows you to modify the distribution of your applications along the SQALE axis.
The settings are:
- Size metric – The metric to use for the size of an application. Default: lines of code
- Number of working hours in a day – The number of productive hours in a work day. Default: 8 hours
- Cost to develop one line of code – The time in minutes to write and test an average line of code. Default: 30
- Rating grid The list of thresholds to use in applying the SQALE density rating scale. Default: 0.1,0.2,0.5,1
Starting Again From Scratch
If you want to start again from scratch, you can reset the SQALE model. To do so, go to Settings > SQALE > Back Up / Restore > Restore Model, select “Default model” and “All languages”, then click on “Restore”.
Copying the SQALE Model to Another Server
You may have tuned your SQALE model on a staging server and now want to deploy it on a production server.
First, back up the SQALE model from your staging server. Go to Settings > SQALE > Back Up / Restore > Back Up Model, select “All languages” and click on “Back Up”.
Then, restore the backed up SQALE model on your production server. Go to Settings > SQALE > Back Up / Restore > Restore Model, select “Backup model”, upload your backup file and click on “Restore”.
The SQALE Governance Model is Global
The SQALE Quality Model, the SQALE Analysis Model, the SQALE rating scale and factors such as the time to develop a line of code are part of the SQALE Governance Model. As such, they are configurable, but only at a global level. It is not possible to tune these values at a project level.
SQALE technical debt is not computed for some of my projects.
It means that the SQALE model is not available for the language of those projects. It happens on versions of SonarQube prior to 4.0 when a language plugin is installed after the SQALE plugin. You have to manually tell SonarQube to retrieve the default SQALE model from the language plugin. To do so, go to Settings > SQALE > Back Up / Restore > Restore Model. Select “Default model” and the language of your project, then click on “Restore”. Once the default model for the language is uploaded, you can run another analysis of your project to compute the SQALE metrics.