code-modularization-evaluator

Code Modularization Evaluator

Evaluate code modularization using the Balanced Coupling Model from Vlad Khononov's "Balancing Coupling in Software Design." This skill helps identify problematic coupling patterns and provides actionable refactoring guidance.

Core Principle

Coupling is not inherently bad—misdesigned coupling is bad. The goal is balanced coupling, not zero coupling.

The fundamental formula:

MODULARITY = (STRENGTH XOR DISTANCE) OR NOT VOLATILITY

A system achieves modularity when:

High integration strength components are close together (same module/service) Low integration strength components can be far apart (different services) Low volatility components can tolerate coupling mismatches The Three Dimensions of Coupling

Always evaluate coupling across these three dimensions:

1. Integration Strength (What knowledge is shared?)

From strongest (worst) to weakest (best):

Level Type Description Example 1 Intrusive Using non-public interfaces Direct database access to another service, reflection on private fields 2 Functional Sharing business logic/rules Same validation duplicated in two places, order-dependent operations 3 Model Sharing domain models Two services using identical entity definitions 4 Contract Only explicit interfaces Well-designed APIs, DTOs, protocols 2. Distance (How far does knowledge travel?)

From closest to most distant:

Methods within same class Classes within same file Classes in same namespace/package Modules in different namespaces Separate services/microservices Services owned by different teams Different systems/organizations 3. Volatility (How often will it change?)

Use Domain-Driven Design subdomain classification:

Core subdomains: High volatility (competitive advantage, frequent changes) Supporting subdomains: Low volatility (necessary but not differentiating) Generic subdomains: Low volatility (solved problems, stable) Decision Framework

When evaluating code, apply this matrix:

Integration Strength Distance Result High High ❌ COMPLEXITY (Distributed monolith) Low Low ❌ COMPLEXITY (Unnecessary abstraction) High Low ✅ MODULARITY (Related things together) Low High ✅ MODULARITY (Independent components apart)

Exception: If volatility is LOW, coupling mismatches are acceptable.

Connascence Analysis

Use connascence to identify specific coupling types. See references/connascence-types.md for detailed examples.

Static Connascence (Compile-time, easier to fix)

Ordered weakest to strongest:

Name (CoN): Components agree on names Type (CoT): Components agree on types Meaning (CoM): Components agree on value meanings (magic numbers) Position (CoP): Components agree on order of values Algorithm (CoA): Components share algorithm logic Dynamic Connascence (Runtime, harder to detect)

Ordered weakest to strongest: 6. Execution (CoE): Order of method calls matters 7. Timing (CoTm): Timing of execution matters 8. Value (CoV): Multiple values must change together 9. Identity (CoI): Must reference same instance

Connascence Rules Minimize overall connascence Minimize connascence crossing module boundaries Maximize connascence within module boundaries Convert stronger connascence to weaker forms As distance increases, connascence should weaken Evaluation Checklist

When analyzing code, check for:

Red Flags (Immediate Action Required) Direct database access to another service's data (Intrusive coupling) Reflection to access private fields Business logic duplicated across services Microservices requiring synchronized deployments CBO (Coupling Between Objects) > 14 for a class Instability index 0.3-0.7 for frequently-changing modules Circular dependencies between modules Warning Signs (Investigate Further) Magic numbers/values shared between components (CoM) Position-dependent parameters in APIs (CoP) Algorithm logic duplicated in multiple places (CoA) Methods must be called in specific order (CoE) Long method chains: a.b().c().d() (Law of Demeter violation) Classes with "Manager", "Helper", "Utility" doing too much Healthy Patterns Contract-based integration between services DTOs that truly abstract internal models High cohesion within modules Single responsibility per class Dependency injection for external dependencies Refactoring Strategies By Integration Strength Problem

Intrusive → Contract Coupling:

Identify all direct dependencies on implementation details Define explicit interface/contract Create adapter layer Route all access through adapter

Functional → Model Coupling:

Extract shared business logic to dedicated module Define clear ownership Consume via explicit dependency

Model → Contract Coupling:

Create integration-specific DTOs Map between internal models and DTOs at boundaries Version contracts independently of models By Connascence Type From To Technique CoM (Meaning) CoN (Name) Replace magic values with named constants/enums CoP (Position) CoN (Name) Use named parameters, builder pattern, or parameter objects CoA (Algorithm) CoN (Name) Extract algorithm to single location, reference by name CoT (Type) CoN (Name) Use duck typing or interfaces CoE (Execution) Explicit Use state machines, builder pattern, or constructor injection CoI (Identity) Explicit Use dependency injection with explicit wiring By Distance Problem

High Strength + High Distance (Distributed Monolith):

Option A: Reduce distance—merge services/modules Option B: Reduce strength—introduce contracts, async messaging

Low Strength + Low Distance (Over-abstraction):

Remove unnecessary abstraction layers Inline overly generic code Combine closely-related classes Analysis Workflow

When asked to evaluate code modularization:

Map the component structure

Identify modules, services, classes Draw dependency graph

Assess Integration Strength

For each dependency, classify: Intrusive/Functional/Model/Contract Flag high-strength cross-boundary dependencies

Measure Distance

Note component locations (same file → different systems) Identify team/ownership boundaries

Evaluate Volatility

Classify each component's subdomain type Note historically frequently-changed areas

Apply the formula

Check: Does strength match distance appropriately? Does volatility excuse any mismatches?

Identify Connascence

Scan for specific connascence types Prioritize: high strength + low locality + high degree

Recommend actions

Prioritize by impact and effort Provide specific refactoring techniques Output Format

Structure your evaluation as:

Modularization Assessment

Summary

[Brief overview of coupling health]

Component Map

[Describe module/service structure]

Coupling Analysis

| Component Pair | Strength | Distance | Volatility | Balance |

|---------------|----------|----------|------------|---------|

| A → B | Model | High | High | ❌ |

Connascence Issues

1. [Specific connascence type]: [Location] - [Impact]

Recommendations

1. Priority 1: [Action] - [Rationale]
2. Priority 2: [Action] - [Rationale]

Refactoring Plan

[Step-by-step approach for highest-priority item]

References For detailed connascence examples: see references/connascence-types.md For coupling metrics: see references/coupling-metrics.md For refactoring patterns: see references/refactoring-patterns.md Limitations Cannot assess runtime behavior without execution context Volatility assessment requires domain knowledge Team/organizational distance requires project context Historical change frequency not available from static analysis alone