💻 computer science

What Characterizes Pairwise Modular Smells?

This study characterizes Pairwise Modular Smells by identifying 19 pair relationship features, training machine learning models on over 6 million entity pairs from 11 Java projects to predict inapt separated and collocated pairs with significant accuracy improvements, and interpreting the results to reveal specific influential factors like dependencies and semantic similarity that drive these architectural flaws.

Original authors: Chenxing Zhong, Daniel Feitosa, Paris Avgeriou, Huang Huang, Wei Song, He Zhang

Published 2026-06-23

📖 5 min read🧠 Deep dive

CC BY 4.0

Original authors: Chenxing Zhong, Daniel Feitosa, Paris Avgeriou, Huang Huang, Wei Song, He Zhang

Original paper licensed under CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ This is an AI-generated explanation of the paper below. It is not written or endorsed by the authors. For technical accuracy, refer to the original paper. Read full disclaimer

Imagine you are the manager of a massive, bustling library. The goal of a good library is to have books organized into logical sections: "Cooking," "History," "Science," etc. This makes it easy for people to find what they need and for librarians to keep things tidy.

In the world of software, these "sections" are called modules. A "good" module groups together files that work closely together (high cohesion) and keeps them separate from files that don't really talk to each other (low coupling).

However, over time, libraries get messy. Books get shuffled into the wrong bins. In software, this mess is called a "Smell." It's not a bad odor, but a sign that something is structurally wrong and might cause headaches later.

The Problem: The "Pairwise Modular Smell" (PairSmell)

In a previous study, the authors introduced a new way to find these messes called PairSmell. Instead of looking at the whole library at once, they look at pairs of books (files).

They ask a simple question: "Do these two files belong in the same section, or should they be in different ones?"

To answer this, they use a panel of "expert librarians" (automated software tools). If all the experts agree that File A and File B should be together, but the library currently has them in different sections, that's a problem. This is called InSep (Inappropriate Separation).

Conversely, if the experts say they should be in different sections, but the library has them stuck together in the same box, that's also a problem. This is called InCol (Inappropriate Collocation).

The Gap: The previous study could find these problems, but it couldn't easily explain why they were problems. It was like a doctor saying, "You have a fever," but not explaining if it's caused by the flu, an infection, or just being in the sun. Developers needed to know why a pair was messy so they could fix it correctly.

The Solution: Investigating the "Personality" of the Pairs

This new paper asks: What specific traits make a pair of files likely to be in the wrong place?

The authors treated this like a detective story. They gathered a list of 19 "personality traits" (characteristics) that describe how two files relate to each other. These traits include:

Dependencies: How many other files does this one talk to?
Shared Words: Do they use the same technical vocabulary?
Size: How big are the files?
Complexity: How hard are they to understand?

They then fed these traits into a Machine Learning "Brain" (a computer model) trained on over 6 million pairs of files from 11 different open-source software projects (like Kafka, Hadoop, and Druid).

The Findings: What Makes a Pair "Smelly"?

The computer learned to spot the "smells" with high accuracy. More importantly, the authors asked the computer to explain which traits were the biggest red flags.

1. For Files That Should Be Together but Are Apart (InSep)

The model found that separated files are likely "smelly" (wrongly separated) if:

They have too many "out-going" connections: Imagine two people in different rooms who are constantly shouting instructions to the same group of people in the hallway. If they rely heavily on the same outside resources, they probably should be in the same room to coordinate better.
They share too many words with the rest of the system: If both files are constantly talking about the same concepts as everyone else in the building, they are likely part of the same "team" and shouldn't be isolated.
They are very simple (few fields): If two files are small and simple but depend on each other, keeping them apart is like putting a left shoe and a right shoe in different boxes. They are too simple to justify being separated.

2. For Files That Are Together but Should Be Apart (InCol)

The model found that files stuck together are likely "smelly" (wrongly grouped) if:

They don't speak the same language (Low Semantic Similarity): If one file is about "Cooking" and the other is about "History," but they are in the same box, that's a mistake. The model checks if they use similar technical terms; if not, they shouldn't be together.
They don't share many words with each other: Even if they are in the same box, if they never mention the same things, they are likely unrelated.
They have too many "in-going" connections: Imagine a single office where 50 different people from other departments come to drop off work. If two files in the same module are being bombarded by requests from everywhere, that module is probably too crowded and needs to be split up to handle the load.

Why This Matters

The authors provide a "User Manual" for developers. Now, instead of just seeing a red flag that says "This is wrong," a developer can see why:

"Oh, these two files are separated, but they both depend on the same 50 other files. I should move them together."
"Oh, these two files are together, but one is a utility tool and the other is a business logic tool, and they have no shared vocabulary. I should split them."

The Bottom Line

This paper takes a complex software problem—figuring out why software modules are messy—and breaks it down into simple, understandable traits. By using a "detective" approach with machine learning, they identified the specific "personality traits" (like how many connections a file has or how many words it shares) that signal a design mistake. This helps developers not just find the mess, but understand the root cause so they can clean it up effectively.

Technical Summary: What Characterizes Pairwise Modular Smells?

Problem Statement
Enhancing the modular structure of existing software systems is a critical challenge. While software modularization techniques attempt to restructure systems into optimal modules, they are often impractical due to the extensive and costly changes required. Conversely, approaches that identify design issues (smells) as refactoring opportunities often suffer from coarse granularity (e.g., at the module level), making it difficult to determine specific refactoring strategies.

To address this, the authors' previous work introduced Pairwise Modular Smell (PairSmell), a fine-grained architectural smell defined as the deviation between the actual modular relation (MR) of a file pair and an apt MR. The apt MR is derived from a consensus of multiple modularization tools. If the actual relation (collocated or separated) contradicts the consensus, it constitutes a smell: InSep (inapt separated, where tools agree they should be together but are separated) or InCol (inapt collocated, where tools agree they should be separated but are together).

However, the definition of PairSmell relies on the "black box" output of modularization tools, making the concept obscure and difficult to explain. Developers lack insight into why a specific pair exhibits a smell. This study aims to explain PairSmell by identifying the specific pair characteristics that make certain entities susceptible to these architectural deviations.

Methodology
The study employs a mixed-method approach combining a rapid literature review, machine learning (ML) modeling, and qualitative analysis:

Rapid Literature Review: The authors reviewed 178 primary studies on software modularization to synthesize a set of candidate features representing relationships between two entities. This process yielded 19 distinct pair characteristics across six dimensions: relatedness, distance, independence, complexity, cohesion, and size.
Dataset Construction: The study utilized a curated dataset of over 6.1 million pairs of entities derived from 11 open-source Java projects (e.g., Kafka, Hadoop, Druid). The dataset includes both separated and collocated pairs, with ground truth labels for InSep and InCol instances established in prior work.
Predictive Modeling:
- Features: The 19 characteristics were used as independent variables.
- Target: Two binary classification tasks were defined: predicting InSep (for separated pairs) and InCol (for collocated pairs).
- Model Selection: Several models (Logistic Regression, SVM, Random Forest) were trained. Support Vector Machines (SVM) were selected as the primary models due to their superior performance.
- Preprocessing: To address collinearity, features with a Spearman's rank correlation ( $\rho$ ) $\ge 0.7$ were removed. Class imbalance was addressed using Inverse Transform Sampling.
Interpretation: The authors used Permutation Feature Importance to identify the most influential characteristics. Partial Dependence Plots (PDP) were generated to visualize how changes in specific feature values affect the probability of a pair being classified as a smell.
Qualitative Validation: Representative examples from the dataset were manually analyzed to illustrate how the identified influential characteristics manifest in real code.

Key Contributions

Systematic Characterization of PairSmell: The study moves beyond merely detecting PairSmell to explaining its emergence. It identifies and interprets the underlying pair characteristics that drive InSep and InCol instances.
Identification of Influential Indicators:
- For InSep (separated pairs that should be together), the most influential indicators are out-going dependencies, terms shared with others (degree), and declared fields (total-fields).
- For InCol (collocated pairs that should be separated), the most influential indicators are semantic similarity (tf-idf), terms shared between the pair (intersection), terms shared with others (degree), and in-going dependencies.
Practical Illustration: The paper provides concrete examples demonstrating how high out-degree or low shared terms correlate with specific smell types, offering actionable insights for developers.

Results

Predictive Performance: The trained SVM models achieved a 58.6% improvement in ROC-AUC over baseline models for collocated pairs and a 34.6% improvement for separated pairs. The models also demonstrated a commendable balance between precision and recall (AUPRC improvements of 1.57x and 2.77x over baselines).
Feature Analysis:
- InSep: High out-going dependencies initially increase the likelihood of a smell (suggesting excessive external coupling), while very low out-degree suggests functional independence justifying separation. High degree (shared terms with others) indicates overlapping responsibilities, making separation inappropriate. Low total-fields in dependent pairs suggests simple, scattered responsibilities that are better kept together.
- InCol: Low semantic similarity (sim-tfidf) and low intersection indicate that collocated entities are unrelated, violating the single responsibility principle. High in-degree suggests the entities have too many responsibilities, potentially overloading the module.
Statistical Significance: Mann-Whitney U tests confirmed significant differences in feature distributions between smelly and non-smelly pairs.

Significance and Claims
The paper claims to advance the understanding of PairSmell by shifting the focus from its prevalence and consequences to its explainability. By linking specific pair characteristics to smell occurrence, the study:

Demystifies PairSmell: It explains why certain pairs are flagged as smells, moving the concept from an opaque tool output to a comprehensible design issue.
Guides Refactoring: The findings offer specific, characteristic-driven strategies for mitigation (e.g., abstracting interfaces to reduce out-degree, or renaming identifiers to improve semantic similarity).
Informs Modular Design: The study suggests that future modularization tools should not only focus on relatedness but also consider independence and size to produce more rational solutions. It highlights that features often used in modularization algorithms may be collinear, suggesting a need for careful feature selection to avoid redundant analysis.

The authors position this work as a foundation for more effective inspection and improvement of software module structures, providing empirical evidence that supports a nuanced perspective on modular design beyond earlier findings focused solely on the prevalence of smells.