Understanding Analysis Results

This chapter describes the main features available in the Explorer. By the end of the chapter, you should be able to make the most of the information and decisions presented by Squore and start applying them to improve your development practices.

Has the Quality of My Project Decreased Since the Previous Analysis?

After completing the analysis of a new version of your project, you will probably want to investigate how it has evolved, more specifically for which artefacts the quality has decreased. Let’s look at the history of the Earth Project (which should be available if your Squore administrator has created the sample projects shipped with the Squore installation) to find out how to spot the worst-scored components in your project.

Log into Squore as the demo user using demo/demo and observe the evolution of the Earth project in the Project Portfolios:

Figure 1. The versions of the Earth Project

The trend arrows before the version names in the Project Portfolios indicate that the overall rating has recently deteriorated (More information about the quality indicator icons is available in Exploring Analysis Results). If you take a closer look at the Technical Debt Trend chart, you can notice that the technical debt is growing for this project.

Figure 2. The Technical Debt Trend chart for the latest version of Earth

You can zoom in on the chart by dragging your mouse over the section of the data you are interested in. After zooming in, you can keep the selected zoom level and move around the chart by holding the Shift key and dragging the chart around, or go back to the original view by clicking the Reset Zoom button in the Chart Viewer.

Figure 3. A zoomed-in section of the Technical Debt Trend chart

Since the trend accelerated in V6, we will focus on this version. Let’s click V6 in the tree and start our evaluation by looking at the scorecard, which rates Earth at E.

Let’s also look at the Code Quality dashboard, which offers more insight into coding violations. Select Code Quality in the Dashboard drop-down list:

Figure 4. The Dashboard drop-down list allows you to see all the dashboards that you have access to

Some values under Artefact Counting, Line Counting and Misra Rule Checking explain the lower score: the application contains more files and functions, more lines of code, fewer comments and more rules violations.

Figure 5. The scorecard for the version V6 of Earth

By now you probably want to find out which components in your project are responsible for increasing the technical debt the application in this version. If you want the Artefact Tree to reflect this information, you can change the sort order to show the worst scores first by clicking on the sort icon

(image:SUM_sorter.png[]) and selecting *{level} > {worst_first}* to display artefacts from worst-scored to best-scored.

Finding Artefacts Using Filters and Search

This section explains the basics of looking for artefacts using filters and search. For a more automated way to find artefact that fit a specific category, take a look at Finding Artefacts Using Highlights.

Click the Filter icon ( SUM filtericon ) in the top-right corner of the Explorer to reveal the Filter Panel. The Filter Panel allows you to set criteria that artefacts need to meet in order to be displayed in the artefact tree or taken into account in charts on the dashboard. For this example, we want to restrict the visibility of artefacts to those rated E and lower:

Figure 6. The Filter Panel with the boxes checked to filter artefacts rated E and lower

Click Apply to apply the changes The Artefact Tree and the dashboard refresh to show results for the artefacts in the levels selected, as shown below:

Figure 7. The filtered Explorer showing artefacts rated E and lower

The notice Filter active is always displayed above the Artefact Tree and the filter icon turns orange when you are using a filter. The tree now only shows artefacts rated E and lower, along with their ancestors, which are greyed out if they are not rated E and lower. On the dashboard, the charts that support displaying filtered information are highlighted with an orange filter icon ( SUM filtericonOrange ) as in the Function Complexity Map. Other charts and scorecard items that cannot be filtered are greyed out.

You can save your filter for later use and even share it with other Squore users by clicking the hamburger menu in the Filter Panel and giving your filter a name.

Figure 8. The filter saving options

Saved filters are displayed in the dropdown list at the top of the Filter Panel so you can reuse them later.

Figure 9. The list of saved filters

For more details about advanced filtering functionality in Squore, consult Advanced Filtering.

While a filter is active, you can still search for other artefacts by typing a search term in the search box. Try typing ma in the search box above the Artefact Tree, and watch the search results list get populated as you type:

Figure 10. The search results for the term entered inside the search box

If you select the highlighted search result in the list above, you will open the dashboard for machine.h.

Let’s go back to our filtered tree. The filter singled out two files whose rating deteriorated that contain functions in the required score range: player.c and write.c. Click on the artefact player.c sub-function to view its dashboard. Note how the scorecard indicates that the artefact has more critical issues than in the previous analysis.

Figure 11. One more critical issue for player.c in this version

You can click the link in the table to directly view the new critical violation on the Findings tab. In this case, the rule NOFALLTHROUGH was broken:

Figure 12. A new critical issue for player.c in this version

Another convenient way to try and find why a project’s quality is deteriorating is to filter on the trend of an artefact.

Select version V6 of Earth again and edit the active filter: Uncheck the boxes for levels E and lower, and select the Deteriorated category in the Evolution section. When applying the filter, you should see the artefacts in the tree that have the SUM deteriorated icon next to their name.

Figure 13. The artefacts that deteriorated in version V6 of Earth

The files you inspected earlier are still here, but there are more deteriorated artefacts that you can start reviewing. If you click on hi_scores_disp(int) for example, which is rated E.

In order to find out where the degradation took place, you can look at the indicators tree to understand where the decline in quality comes from. Expand all the nodes in the indicators tree to reveal the issues with the artefact:

Figure 14. The Indicator Tree for hi_scores_disp(int)

Squore makes it easy to spot the irregularities quickly, like the fact that the Rule Compliance indicator is one of the causes for the worse score in this version. This is probably the first item to review in this function.

By clicking the Rule Compliance indicator in the tree, you can learn more about its history and how it is computed:

Figure 15. The description and history of the Rule Compliance indicator for hi_scores_disp(int)

Finally, you can take a look at the Coding Rules Compliance section of the artefact’s scorecard to confirm the results:

Figure 16. The scorecard for hi_scores_disp(int)

By clicking the link icon, you can directly view the violations for this artefact in the Findings tab.

You can dive further into the analysis results by looking at the information contained in other tabs and assign action items to your team by referring to How Do I Review and Improve My Ratings? or report your progress as explained in Using Comments.

Advanced Filtering

In the previous section, you learned how to filter artefacts based on their overall rating or trend, but Squore allows you to filter on more than the artefact’s main indicator. This section covers filtering on more than one metric, and how you can also save and share your filters with other Squore users.

This example explores how to develop a strategy to reduce cloning in your application by finding the artefacts with the highest cloning that have also been modified since the previous analysis.

Start by displaying the dashboard for version V6 of Earth. In the Filter Panel, clear any existing filter by selecting [Default Filters] and clicking Apply to go back to an unfiltered dashboard.

Figure 17. The [Default Filters] in the Filter Panel

In order to find artefacts that have recently been modified, use Squore’s Stability Index indicator, a feature of the source code parser that computes the amount of changes in a file since the previous analysis. Add a filtering criterion by clicking Add Filter… in the Filter Panel. A popup appears, so you can type the name of the indicator to filter on. Type stability and select Code Stability Index as shown below:

Figure 18. The Filter Panel showing metrics whose names match stability

Clicking Add updates the Filter Panel with a section where you can select Code Stability Index levels to filter on. Since 100% means no changes, select all the levels except for 100%:

Figure 19. The Code Stability Index filter in the Filter Panel (other filters minimised for clarity)

In order to find artefacts with the worst cloning, click Add Filter…, select Measure and find the metric called Cloned Code (CC). Configure this filter as a slider, so we can dynamically change the range of cloning to look out for:

Figure 20. The slider option selected for the Code Cloning metric in the filter popup

Click Add to add your filter. The slider shows you the minimum and maximum values for cloning in this project. Values can be modified either by entering values in the text boxes or by moving the sliders left and right. Move the left slider to about half the range for Code Cloning.

Figure 21. The slider for Code Cloning in the Filter Panel

When clicking Apply to view the results of your filter, the artefact player.c is singled out as a recently modified file with high cloning. By switching to the Software Safety dashboard, you can view details about its stability index in the scorecard.

Figure 22. The Stability Index Information for player.c

Clicking the Findings tab allows you to confirm that the cloning detected by Squore Analyzer was indeed introduced since the latest analysis.

Figure 23. The new cloning violation for player.c

Since this is a new finding in a recently modified file, it makes sense to address the issue to avoid creeping technical debt in the project.

If you want to repeat this exploration at a later time, you can save the filter you just created.

Figure 24. The Filter Panel menu

In order to save a filter, click the hamburger menu in the Filter Panel and select Save as…. The Save Filter popup appears and gives you the option to:

Name your filter
Make it public so other Squore users can apply it and adopt the same cloning exploration practice
Make it available across all projects in Squore

Figure 25. The Save Filter popup

After you save a filter it becomes available in the drop-down list of filters in the Filter Panel:

Figure 26. The filter saving procedure

There are more filtering options for metrics and textual information you can explore directly in Squore’s web interface.

Finding Artefacts Using Highlights

Using Highlights

In the previous section (Finding Artefacts Using Filters and Search), you got familiar with searching and filtering to find the artefact that has a negative impact on the overall rating of a project. in this section, you will learn to master the Highlights functionality, which aims to make the process of finding certain categories of artefacts easier and allows to display additional information about each artefact.

Highlights are flat lists of artefacts ordered in predefined categories for a model.

Let’s try to confirm our findings about the worst and most deteriorated artefacts in Earth. Click on the version V6 of Earth and clear the filter. Click the Highlights tab of the Explorer and select the Top 10 worst artefacts highlight. The list appears as shown below:

Figure 27. The Top 10 worst artefacts in the current version of Earth

The list confirms that some fo the worst-rated artefacts are the ones you explored before. The Highlights table shows you the artefact rating, name and path, and allows you to go to the artefact’s dashboard directly by clicking the artefact name.

Now you can also find the deteriorated artefact hi_scores_disp(int) that you identified with a filter earlier in Finding Artefacts Using Filters and Search: select the Top 10 most deteriorated artefacts highlight to see the artefact appear in the list of deteriorated artefacts in this version.

Figure 28. The Top 10 most deteriorated artefacts in the current version of Earth

Artefacts are sorted by degradation, i.e. the difference between the value of the main indicator in the previous baseline version compared to the current value. By clicking the Export button, you can export the selected items to a CSV file.

If the Export button is grayed out, your license does not include the option to export data to CSV files.

By default, the list of most deteriorated artefacts is compiled based on the previous version of the project. But you can compare results with any other version of the project, including other branches, by choosing the desired reference version in the Reference Panel, as shown below.

Figure 29. Choosing a project version in the Reference Panel

Changing settings in the Reference Panel impacts deltas and trends in most tabs on the dashboard and is covered in more details in Comparing versions with the Reference Panel.

Using Smart Sort

Activating the Smart Sort feature in a highlight allows to identify quickly which artefacts should be reviewed first in order to improve their rating.

Figure 30. Smart Sort checkbox for highlights

Artefacts are sorted using a computed rank which takes into account the displayed indicators rating and their proximity with the scale thresholds for each artefact.

As a result, artefacts with the lowest rank are the ones for which improving the rating should be the most efficient.

Using the Smart Sort feature is only possible if more than one indicator is defined in the highlight.

Creating New Highlights

From the Highlights tab, you can also create new highlights. These new highlights, like your filters can be saved and shared with other Squore users.

Let’s extract more data from the artefacts singled out by your advanced filter in Advanced Filtering, where you found recently modified code with a high cloning ratio. To begin, simply select your saved filter from the Filter Panel and apply it. As you apply and modify the filter, the list of artefacts for the current highlight responds to the filter parameters:

Figure 31. The highlight filtered result

When a filter is applied, you can select a dynamic highlight called Currently Filtered Artefacts. This highlight displays a simple list of artefacts that match the filter that you can add to your review set or export to a CSV file.

Let’s now build a highlight from scratch that uses the same filters and displays more information about the artefacts. Click the hamburger menu next to the list of highlights and select Add Definition. The popup that opens lets you configure the data columns to display for each artefact, as well as apply filters the same way you did in the Filter Panel:

Figure 32. The Highlights Definition popup

The values in the popup above reproduce conditions of the filter you used earlier:

It applies to file and function artefacts (Target Artefact Types)
It displays all results with no limit (Max results number)
It defines two filter conditions
- The measure Code Stability Index is lower than 100% (i.e.: the artefact was modified)
- The measure Cloned Code is higher than 0 (i.e.: there is some cloning)

Please note that you can also hide the path column & the rating column from your Highlights by selecting the checkboxes present in the "Columns" section.

Click Add to create the highlight and view the results. You can also clear the current filter since the highlight defines the same conditions.

Figure 33. Your basic highlight definition for modified artefacts with cloning

In order to add information about the artefacts displayed in the list, click the hamburger menu and select Edit…. The Columns section fo the popup lets you select additional data to display about each artefact. It makes sense to display the cloning ratio and stability details, as well as other indicators and metrics that will help you decide if modifying the code is risky or safe.

Figure 34. Adding columns to the new highlight

When you click Update, the highlight now shows all the requested details for the artefacts:

Figure 35. The extra columns for your new highlight

When you save a highlight definition, you can decide to make it available for all projects that use the same analysis model, and make it public so other Squore users can use it.

Comparing versions with the Reference Panel

A project with a long history or multiple branches can make it difficult to analyse results.

Squore provides the Delta with version component to pick a reference version to compare results with (including versions from other branches). This component is available in the Reference Panel, which is always accessible from the Explorer by clicking the Reference icon ( SUM reference ).

Figure 36. Comparing Earth’s current version with V4

Changing the settings in the Reference Panel impacts the following items in the Explorer:

Trends in the Dashboard and Highlights tabs are computed based on the version you specified instead of the previous version.
Charts that display delta values are updated to compute deltas against the reference version instead of the previous version.
Deltas on the Findings tab are computed based on the specified reference version instead of the previous version.

The Reference icon turns orange and an icon is displayed in the Artefact Tree header when the dashboard is impacted by your settings.

Hide old analyses

It is also possible to hide old versions completely from the Explorer to facilitate analyse results.

Squore provides a calendar allowing to define a date before which any project or branch with a version date older than this reference date will be hidden. This component is available in the Project Portfolios header.

Figure 37. Hide Earth’s versions built before May 11th 2023

Changing this setting impacts the following items in the Explorer:

Temporal charts are updated to hide versions whose version date is older than the reference date.
Versions whose version date is older than the reference date are hidden from the Project Portfolios.

When activated, an orange icon is displayed in the Project Portfolios informing the user that the reference date filter is active.

How Do I Find and Keep Track of Artefacts?

For some projects, you may want to collect artefacts, so you can review them later. Squore enables you to build a Review Set, a list containing artefacts that you want to keep track of. Let’s log in as the demo user to review all the new artefacts added to a project, in order to evaluate their level of quality.

Isolating the new artefacts can be done in three steps:

Log in using the demo user (demo/demo).
Click on version V6 of Earth in the Project Portfolios to display the dashboard for the last version of the project.
Create a filter to display only items in the Evolution column with the status New and apply your changes

You should see the following artefacts in the Artefact Tree:

Figure 38. The new artefacts in the current version of Earth

Squore makes it easy for you to keep track of these artefacts. Click on the icon above the Artefact Tree and select Add Filtered Results to Review Set.

You can now clear your filter, the artefacts you want to review are stored in your Review Set. Click the Review Set tab in the left pane of the explorer to find the items you just saved.

Figure 39. The Review Set filled with new artefacts for version V6 of Earth

At any moment, the artefact currently selected in the Artefact Tree can be sent to the Review Set as well. Simply display the menu for an artefact and click Add to Review Set to add it to the Review Set. Clicking an item in the Review Set pane has the same effect as clicking it in the Artefact Tree: the dashboard refreshes to show the information for that artefact. You can use the left and right arrows in the Review Set pane to go to the previous and next artefact in the list.

If you want to know more about what actions you can take after reviewing artefacts, refer to How Do I Review and Improve My Ratings? and Using Comments.

How can I Understand and Enhance My Model?

Squore provides tools to understand, verify and enhance your model under the Models menu.

The Viewer, a graphical representation of all the analysis models on Squore Server
The Validator, a debug tool for model writers
The Dashboard Editor, which allows customising the dashboards that all users will see
The Ruleset Editor, which allows modifying the model’s ruleset

Users whose global role grants the "View Models" permission have access to the first two tools.

Users whose global role grants the "Modify Models" permission have access to the last two tools.

Viewer

To use the Viewer:

Click Models > Viewer in the toolbar.
Select the analysis model you want to browse.
Select the artefact level you want to browse.
Choose your preferred graphical representation between Space-Tree

and Multi-level pie.
Select whether measures are displayed using their full name or their mnemonic

.

Upon selecting the parameters above, the page is refreshed with the top-level indicators in the model, and you can click each indicator to unveil sub-indicators and their characteristics. You can drag the tree left and right to reveal all sub-levels if necessary. For each indicator selected, Squore displays the following information:

Target is the target artefact type for the selected item
Type is the type of the selected item
Mnemonic is the shortcode for the selected item
description is the description of the selected item
Data Provider is the Data Provider responsible for computing the selected item
MeasureId is the measure ID of the selected item
Computation is the formula used to compute the value of the selected item
ScaleId is ID of the scale associated with the selected item
Levels is the list of levels available for the selected item and their ranges

Figure 40. The software_analytics model presented as a multi-level pie in the Viewer

Validator

If your work involves adjusting the model’s metrics or dashboard, you can use the Validator to verify its integrity during as you make changes. Click Models > Validator to display the diagnostics organised by category, as shown below:

Figure 41. The software_analytics model in the Validator

The Summary tab displays a summary of all the diagnostics run for each category. By clicking any of the other tabs, more details are shown about potential problems found in your model. You can also show the complete XML of the model to understand the errors reported. The XML can be searched by using the Ctrl+F key combination to bring up the search dialogue, and then Ctrl+G to search for the next occurrence of the search term:

Figure 42. The Validator reporting errors

Your Squore administrator can help you get more information model development. You can also refer to the Squore Configuration Guide for a complete reference.

Dashboard Editor

The Dashboard Editor is a graphical editor for the dashboards of a particular model. Dashboards consist of a key performance indicator, a list of tables and one or more columns of predefined charts. With the Dashboard Editor, you can rearrange the information shown on the dashboard for all users, or create a completely new dashboard for a new project role or new group in your project.

In order to use the Dashboard Editor:

Click Models > Dashboard Editor
Select a model and load an existing dashboard

The current dashboard skeleton is loaded in the editor, as shown below:

Figure 43. The Software Analytics model in the Dashboard Editor

The right panel displays your current dashboard, where every chart can be resized or edited, while the left panel allows you to add new charts or tables by dragging them to your current dashboard. When you are satisfied with your changes, you can save your modifications. You can also create a new dashboard, using an existing one as a basis for the new one, or start from a blank canvas.

Your changes are saved in Squore’s workspace folder on the server and are made available to all other Squore users when you click Save.

You can edit a dashboard directly from the Explorer by clicking the Edit Dashboard… entry in the Explorer Settings.

Figure 44. The Edit Dashboard… menu loads the current dashboard in the editor, so you can change it

Ruleset Editor

The Ruleset Editor is a page where you can turn rules on and off, or adjust the categories associated with each rule in your model.

It also allows you to save ruleset templates so that you can use a different set of rules for each project you create

In order to use the Ruleset Editor:

Click Models > Ruleset Editor
Select a model to load its ruleset

The entire ruleset for the current model is then displayed in a table form, and you can use the side filter panel to find the rule you want to modify, as shown below:

Figure 45. The Ruleset Editor displaying the ruleset of the Software Analytics model

You can activate or deactivate a rule by toggling the on/off switch in the table. If you want to make more modifications, click the Edit icon for this rule.

You can also edit multiple rules at once by checking several rules and using the action buttons located at the top of the table. When you save your changes, the configuration is reloaded and every new analysis for this model will use the new settings.

Changes made in the web interface are saved in a workspace folder on the server.

Using Ruleset Templates

Using the Ruleset Editor, you can set up various ruleset templates to modify or ignore rules that do not apply for certain departments or project teams within your organisation.

Users with model edition privileges (see the Modify Models permission in Global Roles) can define templates right from the Ruleset Editor. Project managers can decide to modify existing templates or create new ones from the project wizard. In order to ensure that projects are analysed using company-wide standards, templates can be marked as approved, which prevents them from being modified by other users.

In order to create a ruleset template:

Click on Models > Ruleset Editor
Select an analysis model and locate the Template selection list above the filter tools. For a model where no templates exist yet, only the Duplicate As button is available so can create a new template from the default one.

Figure 46. The ruleset template tools for a model with no custom templates yet

Click Duplicate As to create a new template and enter edit mode. In this example, we are creating a ruleset that contains only rules that apply to the Python programming language. By checking the Approved box, we are defining this ruleset template as read-only for project managers.

Figure 47. Creating a new python-rules ruleset template

Activate, deactivate or modify any rule you want for the template. In this example, we use the filter tools to select all Data Providers, turn off all the rules, and then select the Python-related Data Providers to activate all their rules

Figure 48. The python ruleset template includes the Pylint, pep8 and Squore Analyzer rulesets

When you are satisfied with your rule selection, click Save to save the template. It now appears in the template selection list. You can still modify it as needed, or click Duplicate As to start creating a new template based on your first template.

Figure 49. The saved python ruleset

Project managers can start using your template immediately by selecting it in the Ruleset Edition page of the project wizard, which is displayed after the Data Provider selection screen:

Figure 50. The template selection in the project wizard

Templates can also be applied to projects from the command line using the --rulesetTemplate parameter:

--rulesetTemplate="python-rules"

Managing Ruleset Templates

Export and Import

Aside from creating and deleting ruleset templates, the Ruleset Editor also allows you to export them to XML and import them again. This is useful if you want to copy your templates to another Squore Server or back them up before resetting your server.

Figure 51. The Export / Import tools in the Ruleset Editor

The exported XML file contains the entire ruleset.

Editing the XML template file manually before importing it as a new template is not recommended, however, it can be useful, so you can modify it to determine what happens to the rules not contained in the XML, using the disableOtherRules attribute.

<?xml version="1.0" encoding="UTF-8"?>
<UpdateRules disableOtherRules="false">
  <!--This file is auto-generated, please don't modify.-->
  <UpdateRule measureId="R_MISRA_SAME_DEFPARAMS" disabled="false" categories="SCALE_SEVERITY.MINOR;SCALE_NATURE.NON_CONFORMITY;CHARACTERISTIC.PORTABILITY;SCALE_REMEDIATION.LOW" />
...
</UpdateRules>

Setting disableOtherRules to true deactivates all the other rules in the model that are not specified in the template. By default, or if the attribute is not specified, its value is set to false.

Handling Model Upgrades

Your existing templates will be retained when you upgrade your model to add new rules or upgrade to a new version of Squore:

Existing templates will have all the new rules as disabled (off) by default
The default template will have all the new rules as enabled (on) by default
Projects analysed using project-specific templates (i.e. not using a saved template in the Ruleset Editor) will have all the new rules as enabled (on) by default

Reviewing Multiple Projects

Project Managers may be interested in monitoring several projects as a whole. Squore provides a special dashboard view which compounds information about several projects into an Model/Group Dashboard, which can help you prioritise projects according to their current status.

In order to view the Model/Group Dashboard:

Log into Squore with the demo user.
Click the model name "Software Analytics" in the Project Portfolios.

The dashboard refreshes to show the compounded information for all projects analysed with this model using charts and a summary table of the main indicators, the rating and the trend of each project.

Figure 52. The Model/Group Dashboard for Software Analytics projects

In the quadrants, each project is represented as a bubble . Two indicators define the horizontal and vertical position of the bubble along the axes, while a third indicator defines the bubble size. Let’s see how you should prioritise maintenance work on your project portfolio for the sample projects. Click on the Complexity Volume Vs Cloning quadrant to view the full version:

Figure 53. Complexity Volume Vs Cloning for current Software Analytics projects

In this chart, projects with a high code cloning ratio appear higher, while more complex projects appear more to the right. The size of each bubble indicates the size of the project in terms of source lines of code. Therefore, it may be easier to improve the quality of a project with more cloning but less complexity like Pluto (dark green) than a project with less cloning but more complexity (Mars, in red) As a project manager, you know that as a general rule you need to focus on moving projects towards the bottom-left corner of the chart for a healthy portfolio of projects.

Below the quadrants, Squore displays tables with the values used in the charts, so you can refine the information read in the charts. All the information shown in the analysis model dashboard can be configured by a Squore administrator. Refer to the Squore Configuration Guide for more information.