Measure and Visualize Source Code Quality

Provides an objective and understandable measure of software code quality:

Introduction

Creating and maintaining high-quality software is especially important for critical systems such as those made for the DoD and NASA as well as for software product lines where long-lived, reusable modules are intended to be shared by multiple systems. A vital component of software development is creating high-quality source code that strengthens the reliability and maintainability of the software and has limited technical debt. Technical debt is a measure of how much work would be needed to move from the current to higher-quality code. Preventable debt is incurred when software developers make decisions focused on short-term value—doing what is easy rather than what is right. As debt increases, software maintainability and reliability suffer. High-quality source code is an investment that saves time and money in the long run: users will find fewer bugs, the bugs will be easier to fix, and new features will be easier to add.

Software development teams employ a variety of design techniques, processes, and tools to continually work towards quality code while balancing the overall time and budget demands of the project. The goal of CBR-Insight is to provide an objective and understandable measure of source code quality that can help guide decisions and direct limited resources during software acquisition, development, and sustainment. CBR-Insight is an open source web application that supports the ability of technical and non-technical decision makers to verify that a project’s software implementation follows through on promises around developing and sustaining reliable and maintainable software while managing technical debt.


Dashboard

The CBR-Insight dashboard provides an at-a-glance summary across a number of projects, highlighting overall software code quality and trends in the areas of architecture, complexity, and clarity. Intuitive symbols and colors indicate the relative score, from red/alert to green/check. An overall letter grade (A – F) is also assigned, each with a corresponding color. Trending icons indicate how the area and overall scores have changed relative to a baseline measurement. The dashboard is the starting point for the user to drill down into the details of each project.

CBRI Dashboard

Architecture

One especially important technique to reduce complexity is developing software in a modular and hierarchical fashion. The term architectural complexity is used to describe how a software architecture makes use of modularity and hierarchy. Modularity and hierarchy reduce the dependencies between different pieces of the source code, so a change in one file doesn’t propagate changes to many other files. Similarly, a developer can make a change in one file without having to arrive at a detailed understanding of all of the other affected files. Systems with a better architecture score are those that make good use of modular and hierarchical structures.

Complexity

Software developers also work to manage the complexity within each individual class or file within the source code. Simply put, files that contain less logical complexity, less coupling to other files, fewer methods, and less code to deal with are more reliable and maintainable. Despite this general guidance, some complexity is always expected – there will necessarily be some number of overly complex, highly coupled, and lengthy files in all but the simplest of projects. Systems with a better complexity score are those that have fewer overly complex files.

Clarity

Good developers generally strive to write code that is simple and readable rather than clever. They use descriptive names for classes, methods, and variables that are easy to understand. They add comments to their source code to provide an overview or to describe the intent of the code. While difficult to objectively measure, the clarity of source code has a big impact on reliability and maintainability. Systems with a better clarity score are those that are found to be well commented and more readable.

Project View

The project view provides details on the underlying metrics used to generate the scores for the project and visualizes the calculations over time. The visualizations include color-coded target ranges that were determined by analyzing production-level peer projects as well as a tree-map of file size and complexity organized by the Core Size architecture set. Every section and metric contains accessible descriptions to assist the user in understanding the scores and measurements.

CBRI Project Overview
CBRI Project Overview
CBRI Project Overview
CBRI Project Overview

What is Different

There is a long history of software engineering research in the area of source code quality and numerous existing tools aim at performing automated code quality assessment. What makes CBR-Insight a complementary addition to existing tools is: (i) the calculation of a small, essential set of metrics associated with maintainability, reliability, and technical debt; (ii) using a customizable set of peer projects to determine the target ranges associated with each metric; and (iii) presenting the information in a format preferred by decision makers.


Benefits

Creating and maintaining high-quality software is especially important for critical systems such as those made for NASA and the DoD, and for software product lines where long-lived, reusable modules are intended to be shared by multiple systems. CBR Insight allows program managers and acquisition officials to verify that a project’s software implementation follows through on promises around developing reliable and maintainable software while managing technical debt.

Understand from SciTools

CBR Insight is built on top of the existing Understand code comprehension tool developed by SciTools (scitools.com). Understand, combined with a custom plug-in, is used to perform two specific functions for CBR Insight. First, Understand performs all of the underlying metric calculations. Second, Understand assists software developers in making targeted changes to improve reliability and maintainability and to reduce technical debt. The plug-in generates the same metrics found in the CBR Insight dashboard within the Understand integrated development environment. The combination of Understand’s code comprehension features along with the metrics and visualizations generated by the plug provide the necessary support to address architecture, complexity, and clarity issues.


Open Source (GitHub)

CBRI components are being released on Github as they are completed: https://github.com/StottlerHenke

Note that while CBR Insight is begin released as open source, the underlying Understand software is necessary for CBR Insight to function and must be separately licensed from SciTools. See https://scitools.com/ for more information.


Publications

CBR Insight: Measure and Visualize Source Code Quality

Ludwig, J. and Cline, D.
2019 IEEE/ACM International Conference on Technical Debt (TechDebt), Montreal, QC, Canada, 2019, pp. 57-58.

Static software metrics for reliability and maintainability

J Ludwig, S Xu, F Webber
2018 IEEE/ACM International Conference on Technical Debt (TechDebt), 53-54

Compiling static software metrics for reliability and maintainability from GitHub repositories

J Ludwig, S Xu, F Webber
Systems, Man, and Cybernetics (SMC), 2017 IEEE International Conference on, 5-9


Acknowledgements

This material is based upon work supported by the United States Air Force Research Laboratory under Contract No. FA8650-16-M-6732. The views, opinions, and/or findings contained in this article/presentation are those of the author/presenter and should not be interpreted as representing the official views or policies, either expressed or implied, of the AFRL.

DISTRIBUTION A. Approved for public release: distribution unlimited.