1. 基本概念与命名风格
1.1 下划线命名的核心含义
在 Python 生态中，“下划线命名”通常指将英文单词用下划线分隔，以提升可读性。snake_case 是最常见的命名风格，尤其用于变量和函数名。与之对应的类名通常采用 CamelCase（又称 PascalCase）。
遵循 Python 的下划线命名规范 能让团队成员快速理解代码意图，减少认知成本，提升维护性。通过遵循一致的命名风格，代码的语义更加清晰。下面的代码示例展示了常见的变量和函数命名方式。
# 常见的 snake_case 变量命名
item_count = 42
total_price = 99.99
# 常见的 snake_case 函数命名
def calculate_total(price, tax_rate):
return price * (1 + tax_rate)
1.2 与 PEP 8 的关系
PEP 8 是 Python 官方的编码风格指南，其中明确规定了命名风格的推荐做法：变量名、函数名使用 snake_case，常量使用 ALL_CAPS，类名使用 CamelCase。遵循这份指南就是在实践 最佳实践 的起点。
在模块和包级别，命名应该保持简洁且有意义，避免缩写过度。以下示例展示了在不同作用域的命名风格差异。
# 模块级变量（常量通常使用 ALL_CAPS）
DEFAULT_TIMEOUT = 30
# 函数与变量（snake_case）
def fetch_user_data(user_id):
user_data = {'id': user_id}
return user_data
2. 变量命名规范
2.1 使用 snake_case 命名变量
变量命名的核心是描述性与可读性。使用 snake_case 让单词边界清晰，便于快速阅读和搜索。不要让变量名过长，同时避免拼写错误导致的混淆。
当变量涉及布尔值时，可以使用前缀 is_、has_、can_ 等，让语义更明确。对于集合类型，使用复数形式有助于表达集合的概念。
# 描述性变量名
user_count = 128
is_valid = True
active_items = ['apple', 'banana', 'orange']
2.2 私有与内部变量的前缀约定
在模块或类的内部实现中，使用单前缀下划线 _private_var 表示“非公开的内部实现”，这是 约定俗成的下划线命名规范，并不会真正阻止外部访问。双前缀下划线 __private_var 会触发名称改编（name mangling），用于避免子类的命名冲突。
你需要清晰地分辨公共接口与内部实现，避免暴露无用的内部变量。以下示例演示了不同前缀带来的语义差异。
class DataProcessor:
_cache = {} # 内部实现，不应作为公开 API
__secret_config = {} # 更强的名称改编，用于防冲突
def __init__(self, data):
self.data = data
3. 函数命名规范
3.1 使用 snake_case 命名函数
函数名应描述函数的行为，snake_case 表达的就是单词的自然语言组合。尽量避免模糊的缩写，确保新读者在没有注释的情况下也能理解函数作用。
结合文档字符串（docstring）和类型注解，可以进一步提升函数命名的可读性与可维护性。
def load_user_profile(user_id: int) -> dict:
"""加载用户资料，返回一个字典。"""
# 实现细节省略
return {'id': user_id, 'name': 'Alice'}
3.2 动词优先原则与命名模式
函数名通常以动词开头，明确表达行为。常用前缀包括 get_、set_、compute_、update_、is_ 等，形成清晰的调用契约。
对于对类实例的操作函数，尽量将操作的对象纳入函数名中，避免过度泛化导致义项模糊。
class Calculator:
def compute_total(self, items, tax_rate):
return sum(items) * (1 + tax_rate)
4. 实践要点与最佳实践
4.1 遵循 PEP 8 与命名冲突避免
在团队协作中，遵循 PEP 8 的命名规范是实现一致性的关键。不要使用与 Python 内置名称相同的变量名，以避免覆盖内置函数的风险。
另外，长期可维护的代码要避免在同一作用域中重复使用同一个名称，导致命名冲突和可读性下降。
# 避免覆盖内置函数名
def list(value): # 不推荐的命名
return [value] * 3
def process(items):
length = len(items) # good practice：长度命名清晰
return length
4.2 团队级别的命名规范与工具
为实现 最佳实践 的一致性，可以在项目中引入静态分析工具，如 flake8、pylint 或 ruff，并结合 lint 规则 来强制 snake_case。
持续集成阶段的代码风格检查和在 pre-commit 钩子中运行风格检查，是确保变更符合 下划线命名规范 的有效手段。
# .flake8 配置示例
[flake8]
max-line-length = 88
select = C,E,F,W,B,B9
extend-ignore = E203
