Description

DR-Tools Smell Churn is a tool that works alongside DR-Tools Code Health and the version control system.

Following the same development principles adopted in the DR-Tools Suite, it is a simple-to-use tool that takes as input two files generated from a temporal analysis performed with DR-Tools Code Health, combined with Git to retrieve previous versions.

Requirements and Install Instruction

• Only requirement: JRE version 11
• Download the tool and unzip it to a directory
• We recommend adding the directory to your system PATH — and you're all set!

Main Features

• Command-line (CLI) usage
• Flexible
• Download and run!
• Supported languages: Java (for now)
• Output formats: console and CSV
• Easy visualization and analysis, allowing comparison of smell evolution at different granularities (namespace, type, and method) between two versions

Context

DR-Tools Smell Churn introduces the implementation of a new analysis metric, called smell churn, which allows the evaluation of which code smells were removed, added, or are still present between two analyzed versions.

The basis for creating this metric to assess the insertion/removal of smells is a well-known and widely adopted concept in Software Engineering: code churn. Code churn is used to describe the rate of code modification — or churn rate — over time. It measures the amount of changes made to a specific set of files or lines of code during a defined period, such as a development iteration, a build cycle, or the implementation of a specific feature.

This concept is fundamental to understanding the dynamics of software development and maintenance. It can be calculated in different ways, including counting added, removed, and modified lines of code, the number of commits or revisions made in a given period, or even the number of times a file has been changed. Code churn provides valuable insights into development activity and code stability, and can be used to identify critical areas that require more attention or refactorings.

Usage

DR-Tools Smell Churn uses the open data provided by DR-Tools Code Health to perform its analysis.

Based on the CSV files generated by the tool, it is possible to evaluate the smell churn metric by considering the code smells and the levels of granularity currently supported by DR-Tools Code Health.

The output can be displayed in the console or exported in CSV format, consolidating the results between two system versions.

In the project evolution analysis, an initial version (e.g., v0) is compared with a later version (e.g., v1), verifying whether there has been improvement, degradation, or stability regarding the presence of code smells.

To use it, follow these steps:

1. Clone the project you want to analyze (e.g., poc-project)

prompt> git clone poc-project

2. Checkout the version you want to compare using the following Git command (git checkout <commit-hash-or-tag>)

prompt> git checkout v1

3. Run DR-Tools Code Health in CLI mode using the --analyze command to generate the results for this version

prompt> drtools-code-health \repo\poc-project\src --analyze \temp\poc-project\v1

4. Switch to the current version you want to compare against (repeat the Git command from step 2)

prompt> git checkout v2

5. Repeat step 3, now for the current version (e.g., v2)

prompt> drtools-code-health \repo\poc-project\src --analyze \temp\poc-project\v2

6. Run DR-Tools Smell Churn to analyze the trend of code smells between the two versions

prompt> smell-churn -console \temp\poc-project\v1\.drtools\analysis\20231012_1339_poc-project\smells\drtools-smells-methods.csv \temp\poc-project\v2\.drtools\analysis\20231012_1339_poc-project\smells\drtools-smells-methods.csv