python-design-modularity

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python Design and Modularity

Python设计与模块化

Overview

概述

Readability-first design with explicit module contracts. Keep control flow, data movement, and ownership boundaries visible so code stays maintainable and safe to change.

Treat these recommendations as preferred defaults. When a default conflicts with project constraints, suggest a better-fit alternative and call out tradeoffs and compensating controls (tests, observability, migration, rollback).

以可读性优先为设计原则，明确模块契约。保持控制流、数据流转和职责边界清晰可见，让代码易于维护且可安全变更。

将这些建议视为首选默认方案。当默认方案与项目约束冲突时，建议更适配的替代方案，并说明取舍权衡及补偿控制措施（测试、可观测性、迁移、回滚）。

When to Use

适用场景

Restructuring modules, packages, or ownership boundaries
Breaking apart god classes or deeply nested hierarchies
Choosing between composition and inheritance
Applying Functional Core / Imperative Shell separation
Planning a refactor that touches multiple modules
Reviewing code for readability or architectural clarity

When NOT to use:

Pure performance optimization — see
```
python-concurrency-performance
```
Error handling and resilience patterns — see
```
python-errors-reliability
```
Type contracts and protocol design — see
```
python-types-contracts
```
One-off script or throwaway code with no maintenance horizon

重构模块、包或职责边界
拆分上帝类或深层嵌套层级
选择组合而非继承的场景
应用Functional Core / Imperative Shell分离模式
规划涉及多模块的重构工作
评审代码的可读性或架构清晰度

不适用场景：

纯性能优化 —— 请参考
```
python-concurrency-performance
```
错误处理与弹性模式 —— 请参考
```
python-errors-reliability
```
类型契约与协议设计 —— 请参考
```
python-types-contracts
```
无需长期维护的一次性脚本或临时代码

Quick Reference

速查指南

Keep control flow and data movement explicit.
Keep module ownership and invariants explicit.
Prefer composition by default.
Apply Functional Core / Imperative Shell where it improves testability and separation of concerns.
Separate behavior changes from structural refactors — never mix in the same commit.

保持控制流和数据流转清晰明确。
明确模块职责与不变量。
默认优先使用组合模式。
在提升可测试性和关注点分离的场景下，应用Functional Core / Imperative Shell模式。
将行为变更与结构重构分离 —— 绝不要在同一个提交中混合进行。

Common Mistakes

常见误区

Refactoring behavior and structure simultaneously — conflates two kinds of risk, makes rollback harder, and obscures review. Do one, then the other.
Reaching for inheritance first — deep hierarchies couple unrelated concerns and make reasoning non-local. Default to composition; inherit only when the "is-a" relationship is genuinely stable.
Hidden module coupling — importing implementation details across boundaries creates invisible contracts. Expose explicit public APIs and keep internals private.
Premature abstraction — extracting a shared interface before the second or third concrete use leads to wrong abstractions that are expensive to undo. Wait for duplication to reveal the real seam.
Ignoring the Functional Core / Imperative Shell split — mixing I/O with business logic makes unit testing painful and increases the blast radius of changes. Push side effects to the edges.

同时重构行为与结构 —— 这会合并两类风险，增加回滚难度，并使代码评审难以聚焦。应先完成其中一项，再进行另一项。
优先选择继承 —— 深层继承层级会耦合不相关的关注点，导致代码逻辑难以局部推理。默认采用组合模式；仅当“是一个”的关系真正稳定时才使用继承。
隐藏的模块耦合 —— 跨边界导入实现细节会产生隐形契约。应暴露明确的公共API，将内部实现设为私有。
过早抽象 —— 在出现第二个或第三个具体用例前就提取共享接口，会导致错误的抽象，且后续修正成本高昂。应等待重复模式出现后再确定真正的拆分点。
忽略Functional Core / Imperative Shell拆分 —— 将I/O与业务逻辑混合会使单元测试变得困难，并扩大变更的影响范围。应将副作用移至代码边缘。

Scope Note

范围说明

Treat these recommendations as preferred defaults for common cases, not universal rules.
If a default conflicts with project constraints or worsens the outcome, suggest a better-fit alternative and explain why it is better for this case.
When deviating, call out tradeoffs and compensating controls (tests, observability, migration, rollback).

将这些建议视为常见场景下的首选默认方案，而非通用规则。
如果默认方案与项目约束冲突或会导致更差的结果，建议更适配的替代方案，并解释为何该方案更适合当前场景。
当偏离默认方案时，需说明取舍权衡及补偿控制措施（测试、可观测性、迁移、回滚）。

Invocation Notice

调用说明

Inform the user when this skill is being invoked by name:
```
python-design-modularity
```
.

当调用此技能时，需告知用户技能名称：
```
python-design-modularity
```
。

References

参考资料

```
references/design-rules.md
```

references/readability-and-complexity.md

```
references/module-boundaries.md
```
```
references/functional-core-shell.md
```
```
references/refactor-guidelines.md
```

```
references/design-rules.md
```

references/readability-and-complexity.md

```
references/module-boundaries.md
```
```
references/functional-core-shell.md
```
```
references/refactor-guidelines.md
```