1 遵循命名规范

模块命名应该：

• 使用小写字母和下划线（snake_case）
• 避免使用Python关键字和内置模块名
• 具有描述性且简洁

反例： MyModule.py, math.py

正例： data_utils.py, report_generator.py

2 编写模块文档字符串

每个模块顶部应该包含一个文档字符串，说明模块的目的、主要功能和用法。

"""
数据预处理工具集

提供常用的数据清洗、转换和特征工程功能

主要功能:
- 处理缺失值
- 标准化/归一化
- 分类变量编码
- 特征选择

示例:
    >>> from data_utils import clean_missing_values
    >>> df = clean_missing_values(df, strategy='mean')
"""

3 避免模块级副作用

模块导入时不应执行任何实质性操作（除了初始化）。将所有可执行代码封装在函数或if __name__ == '__main__':块中。

# 反例: 模块导入时立即执行操作
print("Initializing module...")  # 导入时会立即执行

# 正例: 将执行代码放在main保护块中
def main():
    print("This runs only when executed directly")
    
if __name__ == '__main__':
    main()

4 合理使用__init__.py文件

在包目录中，__init__.py文件用于：

• 标记目录为Python包
• 定义包级别的导入
• 执行包初始化代码

# my_package/__init__.py
from .module1 import feature1, feature2
from .subpackage import helper_function

__version__ = "1.0.0"
__all__ = ['feature1', 'feature2', 'helper_function']

5 控制导入内容

使用__all__变量明确指定模块的公共API：

# 在 my_module.py 中
__all__ = ['public_function', 'PublicClass']

def public_function():
    pass

def _private_function():
    pass

class PublicClass:
    pass

class _PrivateClass:
    pass

6 处理循环导入

循环导入会导致运行时错误。解决方法：

• 重构代码消除循环依赖
• 将导入放在函数/方法内部
• 使用import语句而非from...import

# 模块A.py
# 反例: 在顶部导入模块B
import moduleB  # 如果模块B也导入模块A，会导致循环导入

# 正例: 在函数内部导入
def some_function():
    import moduleB  # 延迟导入
    # 使用moduleB

7 模块版本控制

使用__version__属性管理模块版本：

# 在模块顶部定义
__version__ = "1.2.3"

# 在setup.py中使用
setup(
    name="my_module",
    version=__version__,
    # ...
)

8 提供清晰的导入路径

设计模块结构时考虑导入体验：

# 反例: 嵌套过深
from my_package.utils.helpers.strings import sanitize_input

# 正例: 合理使用__init__.py扁平化导入
from my_package import sanitize_input

9 包含单元测试

为模块编写测试，并放置在tests目录中：

my_module/
├── my_module/          # 主包
│   ├── __init__.py
│   ├── core.py
│   └── utils.py
├── tests/              # 测试目录
│   ├── test_core.py
│   └── test_utils.py
├── setup.py
└── README.md

10 打包与分发

使用setuptools创建setup.py文件，方便模块分发：

from setuptools import setup, find_packages

setup(
    name="my_utility",
    version="0.1.0",
    packages=find_packages(),
    install_requires=[
        'requests>=2.25',
        'pandas>=1.2'
    ],
    author="Your Name",
    description="A collection of utility functions",
    long_description=open('README.md').read(),
    long_description_content_type="text/markdown",
    url="https://github.com/you/my_utility",
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License"
    ]
)