Finding Technical Health Challenges

Owned by Chris Martin (Deactivated)
Last updated: Jan 25, 2022 by Maxwell Chandler (Unlicensed)
5 min read

Table of Contents:

 

There is a wealth of information about code quality and design quality in the File List tab of the CodeMRI® excel file.  A common question is: “If I want to improve the economics of my codebase, should I focus on improving design quality or code quality?”  Research shows that improving design quality has a slightly more significant impact on economics, although both are important.

Design Quality

To find out which files are included in a specific core, go to the reports folder and open the CodeMRI-<codebase>-<language> file, click on the File List tab and navigate to column H (you can also sort by Col H). This column, labeled Cyclic Group Size, lists the size of the core that each individual file is in (if the file is not in a core, the size is 0). A refactoring effort is required to break the linkages between the files listed as being part of a core.  In order to guide this refactoring, Silverthread provides the Technical Health Improvement Plan (see below).

Code Quality

To find out which files have high McCabe Cyclomatic Complexity, go to the reports folder and open the CodeMRI-<codebase>-<language> file, and click on the File List tab and navigate to column T (you can also sort by Col T). This column, labeled Max Cyclomatic, is the numeric value of McCabe Cyclomatic Complexity.  As McCabe Cyclomatic Complexity is a code quality metric – within a file – it can be reduced by working to reduce complexity within that specific file listed in column A.

Improving Technical Health

Creating a Technical Health Improvement Plan

The Technical Health Improvement Plan (THIP) is an Excel file that provides engineers with the most efficient series of steps determined by CMRI to eliminate Core(s) from a scanned codebase. This includes metrics including the impact of each broken relationship, in which files to locate the erroneous relationships, and more. You can use the THIP to focus on design & architecture health within your software development organization with tools that provide continuous real-time insight. By scanning the codebase as development and/or refactoring continue, you can confidently improve, prevent the introduction of design problems, and manage the software architecture over time. 

  1. Create & select a project and system in CMRI.

  2. Produce Health Diagnostics reports for the system.

  3. After creating reports, run the  produce_thip job:

job run produce_thip

a. By default, the THIP will only consider critical Cores (150+ files) and will pass over any emerging Cores.

b. To customize the minimum Core size for the THIP to eliminate emerging cores, run produce_thip with a size threshold of 29:

job run produce_thip –-size 29

The THIP will be placed in the vault/reports/<project>/<system name>-<system version>/<language> subdirectory. One report per codebase language will be generated.

Please note that produce_thip can take considerable time to run. Due to the complexity of the algorithms involved in breaking apart cores, it is difficult to pin down an estimated time for the process. In practice, the THIP has taken anywhere from a half hour to a week for some very large codebases.

Using the Technical Health Improvement Plan

The THIP provides a list of steps that, if taken, will reduce the core to 150 (or the custom selected size).  For the core reduction to be accomplished, each step must occur in the order listed.  For example, in the figure below

an 8% reduction in the core size can be accomplished by completing steps 1-7 in that sequential order.  If the engineers continue the refactoring to complete steps 8, 9, and 10 in the example above, then a 20% reduction in the core size should occur.  The details required to complete each step are provided on the Linkages tab.

The most practical way to reduce a core in a refactoring effort is to look at the first 10 items on the recommended list and break those linkages – leaving out those that are very difficult.  Then rerun the THIP.  Because there are a number of ways to break apart a core, this approach often finds a way around the difficult linkages.

Modifying the Technical Health Improvement Plan

It may not be practical to complete the steps in the sequential order.  The Silverthread THIP calculates the most efficient steps, but doesn’t know anything about how easy or difficult those steps would be to accomplish.

Decomposing a core can be thought of as untangling fishing line:  it isn’t useful to start at the center of the knot.  The most successful fishing-line-untanglers start with the simple parts of the knot, and then work their way toward the more complex parts.  Once some of the simple parts are done, the parts that looked difficult have become easier.

After a detailed technical analysis of the THIP, the engineering team may decide to prioritize or exclude certain recommended steps.

There are thip commands which are meant to be used in conjunction with a Technical Health Improvement Plan. The general workflow is:

  • Create a Technical Health Improvement Plan

  • Use thip commands to alter priority on certain steps.

  • Re-run the Technical Health Improvement Plan to see results 

Using the THIP commands

  • List all the cores associated with a specific language:

system thip core list [–language <language>] [–output-format <format>] [–out <output_file>]

  • List all the steps in a specific core:

system thip step list [–language <language>] [–core <core_number>] [–output-format <format>] [–out <output_file>]

Note: this lists steps for the provided language/core combination along with the following basic metrics about the provided steps:

STEP: The step number used to reference the step in operations.

FROM FILE: The file originating the relationships to cut.

TO FILE: The file containing referenced entities in the relationships to cut.

ENTITIES MODIFIED: The number of entity relationships to cut.

CORE SIZE: The core size after the provided step and all previous steps are completed.

PRIORITY: True if the step is prioritized, False

EXCLUDED: True if the step will be removed next time produce_thip is run, False

  • Prioritize steps. Prioritization of a step will flag a step as “priority”. Priority steps are always included, and moved to the top of the list of steps. The order of priority steps in subsequent runs of the Technical Health Improvement Plan are the order in which they were prioritized.

system thip step prioritize [–steps <steps>] [–language <language>] [–core <core_number>]

  • Exclude steps. There are valid reasons for maintaining specific relationships and wanting to exclude them from the THIP, including the possibility that it is a false positive.

system thip step exclude [--steps <steps>] [--language <language>] [--core <core_number>]

  • Note that adding steps to this exclusion list may significantly change any following steps in the Technical Health Improvement Plan as the core decomposer will need to find an alternate (and less optimal) route to take.

 

Customer Support

Phone: 800-674-9366 (9am - 5pm Eastern Time)

Email: support@silverthreadinc.com