Python3 + 变量命名规则与约定详解
一、官方命名规则(必须遵守)
1. 合法字符集
变量名只能包含:
- 大小写字母(a-z, A-Z)
- 数字(0-9)
- 下划线(_)
2. 禁止数字开头
合法:user_age, age123
非法:123age, $money
3. 区分大小写
name和Name是两个不同的变量
4. 禁止使用关键字
Python 内置关键字不能用作变量名(如if, def, class等)。
检查关键字方法:
python
import keyword
print(keyword.kwlist) # 打印所有关键字
二、PEP 8 官方风格指南(推荐遵守)
1. 命名风格分类
风格 | 示例 | 适用场景 |
蛇形命名法(snake_case) | user_name, max_attempts | 变量名、函数名、方法名 |
大驼峰命名法(PascalCase) | UserProfile, HttpRequest | 类名、异常名 |
全大写 + 下划线(UPPER_SNAKE_CASE) | MAX_SIZE, DEFAULT_TIMEOUT | 常量 |
单前导下划线(_private) | _internal_var, _private_method | 内部使用(非公开 API),约定不被外部访问 |
单末尾下划线(trailing_) | class_, list_ | 避免与 Python 关键字冲突 |
双前导下划线(__private) | __mangled_attr, __private_method | 类私有成员,触发名称修饰(Name Mangling) |
双前导双末尾(special) | __init__, __str__ | 特殊方法(魔法方法),由 Python 解释器调用 |
2. 变量命名建议
- 见名知义:使用描述性名称,避免无意义缩写
坏:a, x, tmp
好:user_id, total_amount, temp_file_path - 避免冗余:类属性名无需重复类名
坏:User.user_name
好:User.name - 布尔变量:使用is_或has_前缀
示例:is_valid, has_permission, enabled - 集合类型:使用复数或集合名词
示例:users, student_scores, config_options
三、Python3 + 特有的命名约定
1. 类型提示相关
- 类型变量使用 PascalCase:T, AnyStr, MyCustomType
python
from typing import TypeVar
T = TypeVar('T')
def get_item(lst: list[T]) -> T:
return lst[0]
- 泛型别名使用全大写:Vector, ConnectionOptions
python
from typing import Dict, str
Config = Dict[str, str]
2. 海象运算符变量
通常使用短名称(如n, res)表示临时计算结果:
python
if (n := len(data)) > 10:
print(f"Large data: {n} elements")
四、特殊场景处理
1. 与内置函数 / 类型冲突
使用单末尾下划线:
python
list_ = [1, 2, 3]
# 避免覆盖内置list
dict_ = {"key": "value"}
# 避免覆盖内置dict
2. 解构赋值
使用_忽略不需要的值:
python
_, status_code = fetch_data()
# 只关心第二个返回值
3. 多用途变量
使用_作为循环计数器(表示该变量不被使用):
python
for _ in range(5): # 不需要循环索引
print("Hello")
五、命名规范工具链
1. 静态代码检查
- flake8:检查命名是否符合 PEP 8
- bash
flake8 --select N800,N801,N802 your_file.py
# 只检查命名规则
- pylint:提供更详细的命名建议
- bash
pylint --disable=all --enable=invalid-name your_file.py
2. IDE 自动格式化
- PyCharm:Settings → Code Style → Python → Naming conventions
- VS Code:安装autopep8插件,设置editor.formatOnSave为true
六、常见错误与避坑指南
1. 混淆命名风格
- 坏:userName = "Alice"(混合使用驼峰和蛇形)
- 好:user_name = "Alice"(统一使用蛇形)
2. 过度缩写
- 坏:num_of_emp(难以理解)
- 好:number_of_employees(清晰明确)
3. 双下划线名称修饰陷阱
双前导下划线会触发名称修饰,导致无法直接访问:
python
class MyClass:
__private = 10
obj = MyClass()
print(obj.__private)
# 报错
print(obj._MyClass__private)
# 可访问(不推荐)
总结:命名规则速查表
场景 | 规则 | 示例 |
变量 / 函数 / 方法 | 蛇形命名法(小写 + 下划线) | calculate_total |
类 / 异常 | 大驼峰命名法(大写开头) | HttpRequestError |
常量 | 全大写 + 下划线 | MAX_CONNECTIONS |
内部使用 | 单前导下划线 | _internal_helper |
避免关键字冲突 | 单末尾下划线 | type_, list_ |
临时 / 忽略值 | 单个下划线 | _, status = fetch_data() |
类私有成员 | 双前导下划线(触发名称修饰) | __private_method |
特殊方法 | 双前导双末尾 | __len__, __repr__ |
遵循 PEP 8 命名约定不仅能提高代码可读性,还能减少团队协作中的沟通成本。建议结合静态检查工具,在开发阶段及时发现命名问题。对于不确定的命名,优先选择更具描述性的名称,而非追求简洁。