Back to Details

modular-code

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Modular Code Organization

模块化代码组织

Write modular Python code with files sized for maintainability and AI-assisted development.
编写模块化Python代码，控制文件大小以提升可维护性并适配AI辅助开发。

File Size Guidelines

文件大小指南

LinesStatusAction
150-500OptimalSweet spot for AI code editors and human comprehension
500-1000LargeLook for natural split points
1000-2000Too largeRefactor into focused modules
2000+CriticalMust split - causes tooling issues and cognitive overload
行数状态操作
150-500最优AI代码编辑器和人类理解的理想区间
500-1000过大寻找自然拆分点
1000-2000过大重构为聚焦的模块
2000+严重必须拆分 - 会导致工具问题和认知过载

When to Split

何时拆分

Split when ANY of these apply:
  • File exceeds 500 lines
  • Multiple unrelated concerns in same file
  • Scroll fatigue finding functions
  • Tests for the file are hard to organize
  • AI tools truncate or miss context
满足以下任一条件时进行拆分：
  • 文件超过500行
  • 同一文件包含多个不相关的关注点
  • 查找函数时需要频繁滚动
  • 文件对应的测试难以组织
  • AI工具截断或丢失上下文

How to Split

如何拆分

Natural Split Points

自然拆分点

  1. By domain concept: 
    auth.py
    → 
    auth/login.py
    , 
    auth/tokens.py
    , 
    auth/permissions.py
  2. By abstraction layer: Separate interface from implementation
  3. By data type: Group operations on related data structures
  4. By I/O boundary: Isolate database, API, file operations
  1. 按领域概念拆分：
    auth.py
    → 
    auth/login.py
    、
    auth/tokens.py
    、
    auth/permissions.py
  2. 按抽象层拆分：将接口与实现分离
  3. 按数据类型拆分：将相关数据结构的操作分组
  4. 按I/O边界拆分：隔离数据库、API、文件操作

Package Structure

包结构

feature/
├── __init__.py      # Keep minimal, just exports
├── core.py          # Main logic (under 500 lines)
├── models.py        # Data structures
├── handlers.py      # I/O and side effects
└── utils.py         # Pure helper functions
feature/
├── __init__.py      # 保持精简，仅用于导出
├── core.py          # 主逻辑（少于500行）
├── models.py        # 数据结构
├── handlers.py      # I/O和副作用
└── utils.py         # 纯辅助函数

DO

建议做法

  • Use meaningful module names (
    data_storage.py
    not 
    utils2.py
    )
  • Keep 
    __init__.py
    files minimal or empty
  • Group related functions together
  • Isolate pure functions from side effects
  • Use snake_case for module names
  • 使用有意义的模块名称（如
    data_storage.py
    而非
    utils2.py
    ）
  • 保持
    __init__.py
    文件精简或为空
  • 将相关函数分组
  • 将纯函数与副作用隔离
  • 模块名称使用snake_case命名法

DON'T

避免做法

  • Split files arbitrarily by line count alone
  • Create single-function modules
  • Over-modularize into "package hell"
  • Use dots or special characters in module names
  • Hide dependencies with "magic" imports
  • 仅按行数随意拆分文件
  • 创建仅包含单个函数的模块
  • 过度模块化导致"包地狱"
  • 模块名称中使用点或特殊字符
  • 通过"魔法导入"隐藏依赖

Refactoring Large Files

重构大文件

When splitting an existing large file:
  1. Identify clusters: Find groups of related functions
  2. Extract incrementally: Move one cluster at a time
  3. Update imports: Fix all import statements
  4. Run tests: Verify nothing broke after each move
  5. Document: Update any references to old locations
拆分现有大文件时：
  1. 识别集群：找到相关函数组
  2. 逐步提取：每次移动一个函数组
  3. 更新导入：修复所有导入语句
  4. 运行测试：每次移动后验证功能正常
  5. 更新文档：更新所有指向旧位置的引用

Current Codebase Candidates

当前代码库候选对象

Files over 2000 lines that need attention:
  • Math compute modules (scipy, mpmath, numpy) - domain-specific, may be acceptable
  • patterns.py - consider splitting by pattern type
  • memory_backfill.py - consider splitting by operation type
超过2000行需要关注的文件：
  • 数学计算模块（scipy、mpmath、numpy）- 特定领域，可能可接受
  • patterns.py - 考虑按模式类型拆分
  • memory_backfill.py - 考虑按操作类型拆分

Sources

参考来源