code-modularization-evaluator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

使用Vlad Khononov所著《软件设计中的耦合平衡》一书中的平衡耦合模型评估代码模块化。该工具可帮助识别有问题的耦合模式，并提供可落地的重构指导。

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

耦合本身并非坏事——设计不当的耦合才是问题所在。 目标是实现平衡耦合，而非零耦合。

基础公式：

MODULARITY = (STRENGTH XOR DISTANCE) OR NOT VOLATILITY

系统实现模块化的条件：

高集成强度的组件彼此靠近（同一模块/服务）
低集成强度的组件可分散部署（不同服务）
低易变性组件可容忍耦合不匹配

The Three Dimensions of Coupling

耦合的三个维度

Always evaluate coupling across these three dimensions:

需始终从以下三个维度评估耦合：

1. Integration Strength (What knowledge is shared?)

1. 集成强度（共享哪些知识？）

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

从最强（最差）到最弱（最佳）排序：

级别	类型	描述	示例
1	侵入式（Intrusive）	使用非公开接口	直接访问其他服务的数据库、通过反射访问私有字段
2	功能式（Functional）	共享业务逻辑/规则	相同验证逻辑在两处重复、依赖执行顺序的操作
3	模型式（Model）	共享领域模型	两个服务使用完全相同的实体定义
4	契约式（Contract）	仅依赖显式接口	设计良好的API、DTO、协议

2. Distance (How far does knowledge travel?)

2. 距离（知识传递的跨度？）

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?)

3. 易变性（变更频率？）

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

共生（Connascence）分析

Use connascence to identify specific coupling types. See

references/connascence-types.md

for detailed examples.

利用共生概念识别特定耦合类型。详细示例请参见

references/connascence-types.md

。

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

按从弱到强排序：

名称共生（CoN）：组件使用统一的命名
类型共生（CoT）：组件使用统一的类型
含义共生（CoM）：组件对值的含义达成一致（如魔法值）
位置共生（CoP）：组件对值的顺序达成一致
算法共生（CoA）：组件共享算法逻辑

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

按从弱到强排序： 6. 执行共生（CoE）：方法调用顺序有要求 7. 时序共生（CoTm）：执行时序有要求 8. 值共生（CoV）：多个值必须同步变更 9. 标识共生（CoI）：必须引用同一实例

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)

红色预警（需立即处理）

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

组件间共享魔法值/常量（CoM）
API参数依赖位置顺序（CoP）
算法逻辑在多处重复（CoA）
方法必须按特定顺序调用（CoE）
长方法链：
```
a.b().c().d()
```
（违反迪米特法则）
包含“Manager”“Helper”“Utility”等名称的类职责过多

Healthy Patterns

健康模式

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

侵入式 → 契约式耦合：

识别所有对实现细节的直接依赖
定义显式接口/契约
创建适配层
所有访问均通过适配层路由

功能式 → 模型式耦合：

将共享业务逻辑提取到专用模块
明确所有权
通过显式依赖进行调用

模型式 → 契约式耦合：

创建集成专用的DTO
在边界处映射内部模型与DTO
契约版本与模型独立管理

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

原类型	目标类型	技术手段
CoM（含义共生）	CoN（名称共生）	用命名常量/枚举替换魔法值
CoP（位置共生）	CoN（名称共生）	使用命名参数、构建器模式或参数对象
CoA（算法共生）	CoN（名称共生）	将算法提取到单一位置，通过名称引用
CoT（类型共生）	CoN（名称共生）	使用鸭子类型或接口
CoE（执行共生）	显式控制	使用状态机、构建器模式或构造函数注入
CoI（标识共生）	显式控制	使用依赖注入并显式配置

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

高强度 + 远距离（分布式单体）：

选项A：缩短距离——合并服务/模块
选项B：降低强度——引入契约、异步消息

低强度 + 近距离（过度抽象）：

移除不必要的抽象层
内联过于通用的代码
合并紧密相关的类

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:

markdown

undefined

评估结果按以下结构组织：

markdown

undefined

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	❌

组件对	强度	距离	易变性	平衡状态
A → B	模型式	高	高	❌

Connascence Issues

共生问题

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

[具体共生类型]：[位置] - [影响]

Recommendations

建议

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

优先级1：[行动] - [理由]
优先级2：[行动] - [理由]

Refactoring Plan

重构计划

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

undefined

[最高优先级项的分步实施方法]

undefined

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
```

详细共生示例：参见
```
references/connascence-types.md
```
耦合指标：参见
```
references/coupling-metrics.md
```
重构模式：参见
```
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

若无执行上下文，无法评估运行时行为
易变性评估需要领域知识
团队/组织层面的距离需要项目上下文
仅通过静态分析无法获取历史变更频率