Python函数名必须用小写字母加下划线（snake_case），模块名须全小写、无特殊字符且不与内置名冲突，避免双下划线非init文件。

Python 函数名必须用小写字母加下划线

Python 官方 PEP 8 明确要求函数名使用 snake_case，即全小写、单词间用单个下划线连接。这不是风格偏好，而是影响可读性和工具兼容性的硬性约定。

常见错误包括：getUserName（驼峰）、GET_USER_NAME（大写常量风格）、get_user__name（双下划线）、get-user-name（短横线，语法错误）。

• def calculate_total_price() ✅ 合理
• def CalculateTotalPrice() ❌ 类名风格，易与 class 混淆
• def _internal_helper() ✅ 单下划线前缀表示“受保护”，非公开
• def __private_method() ⚠️ 双下划线触发 name mangling，仅限真正私有逻辑

模块名要简短、全小写、无特殊字符

模块文件名即导入名，直接影响 import 语句和 IDE 补全。它必须是合法的 Python 标识符，且不能含点号、中划线或空格——否则会直接报错 ImportError: invalid syntax 或 ModuleNotFoundError。

典型问题场景：把 my-api-client.py 当模块导入，结果写 import my-api-client 导致语法错误；或用 2025_utils.py 开头数字导致无法导入。

• ✅ 正确命名：requests_cache.py → import requests_cache
• ✅ 正确命名：db_helpers.py → from db_helpers import connect
• ❌ 错误命名：data-v2.py（含短横线，文件可存但无法 import）
• ❌ 错误命名：1main.py（开头数字，标识符非法）

避免与内置函数或标准库模块重名

覆盖内置名（如 list、str、open）会导致后续调用异常，且 IDE 往往不报错，排查困难。同理，自定义模块命名为 json.py 或 os.py 会屏蔽标准库，引发不可预知行为。

例如：在项目根目录建了 json.py，再执行 import json，实际导入的是你本地那个空文件，而非标准库 json 模块，接着调用 json.loads(...) 就会抛 AttributeError。

• ⚠️ 高危重名：str.py、dict.py、time.py、math.py
• ✅ 安全替代：str_utils.py、dict_tools.py、time_helpers.py
• 检查是否冲突：运行 python -c "import json; print(json.__file__)" 看路径是否指向标准库

包内模块名不要用 __init__.py 以外的双下划线文件

Python 包机制依赖 __init__.py 触发识别，但其他以双下划线开头的模块（如 __main__.py、__version__.py）虽语法合法，却容易被误认为特殊文件而被某些打包工具（如 setuptools）忽略，或在 pip install -e . 时未正确包含。

更隐蔽的问题是：IDE 和静态分析工具（如 mypy）可能跳过这些文件的类型检查，导致 bug 潜伏。

• ✅ 推荐方式：version.py 存版本字符串，__init__.py 中 from .version import __version__
• ✅ 推荐方式：cli.py 放命令行入口，通过 if __name__ == "__main__": 控制执行
• ❌ 不推荐：__cli__.py、__utils__.py —— 无实际收益，徒增混淆

def get_version() -> str:
    return "1.2.3"
version.py —— 清晰、可导入、可测试、无歧义

模块和函数命名看着简单，真正卡住人的往往是那些“能跑但不对”的边界情况：比如名字合法却遮蔽了内置函数，或者文件名合法却让 import 走错了路径。留心这些细节比记住规则更重要。