Python之变量命名规则详解_Python

在 python 编程中，变量命名看似是 “小事”，却直接影响代码的可读性、可维护性，甚至团队协作效率。

糟糕的命名会让后续调试、迭代变得举步维艰 —— 想想看，当你接手一个包含a1、str_1、func_x这类变量的项目时，是不是要花大量时间猜测它们的用途？

这篇文章将从 “基础规则” 到 “进阶规范”，结合 “三要三不要” 原则，避开常见坑。

1. 硬性规则

在谈 “规范” 之前，必须先明确 python 语法层面的 “强制要求”—— 违反这些规则，代码会直接报错，根本无法运行。

只能包含字母、数字和下划线变量名的第一个字符必须是字母（a-z, a-z）或下划线（_），不能以数字开头。

✅ 合法：user_name、age_18、_total_score
❌ 非法：18_age（以数字开头）、user-name（包含连字符）、user@name（包含特殊符号）

区分大小写python 对大小写敏感，user和user是两个完全不同的变量。示例：

user = "lyle"
user = "tom"

print(user)  # 输出：lyle
print(user)  # 输出：tom

不能使用关键字 / 保留字关键字是 python 内置的、有特殊含义的单词（如if、for、class等），不能作为变量名。如何查看所有关键字？可以用以下代码：

import keyword

print(keyword.kwlist)
print(len(keyword.kwlist)

['false', 'none', 'true', 'and', 'as', 'assert', 'async', 'await', 'break', 'class', 'continue', 'def', 'del', 'elif', 'else', 'except', 'finally', 'for', 'from', 'global', 'if', 'import', 'in', 'is', 'lambda', 'nonlocal', 'not', 'or', 'pass', 'raise', 'return', 'try', 'while', 'with', 'yield']
35

❌ 错误示例：if = 10（if是关键字）、class = "学生"（class是关键字）

2. “三要” 原则

语法规则保证代码能运行，而 “三要” 原则则保证代码 “好读、好维护”。核心思路是：让变量名 “自解释”，减少注释依赖。

2.1. 要体现变量的 “实际作用”，拒绝 “无意义命名”

如果一个变量名只能告诉你 “它是个字符串” 或 “它是个数字”，却无法说明 “它存的是什么内容”，那就是无效命名。

❌ 反面示例：str_1、num_1分别存的是什么？—— 需要猜！

str_1 = "zhangsan@example.com"
num_1 = 25

print(f"用户信息：{str_1}, {num_1}")

✅ 正面示例：一看就知道存的是“用户邮箱”和“用户年龄”

user_email = "zhangsan@example.com"
user_age = 25

print(f"用户信息：{user_email}, {user_age}")

2.2. 要让变量名 “自解释”，减少注释依赖

如果一个变量需要额外加注释才能说明用途，说明命名效率极低 —— 工程变大后，变量可能出现在多个文件中，注释容易遗漏或过时，导致可读性骤降。

❌ 反面示例（依赖注释）：

# 注释：这个变量存的是用户是否已实名认证（true=已认证，false=未认证）
user_flag: bool = true  # 问题：flag太泛，没有说明“什么flag”

✅ 正面示例（自解释，无需注释）：

# 优点：变量名直接说明“用户是否已实名认证”，无需额外注释
user_is_certified: bool = true

2.3. 函数命名要 “明确功能”，不要怕 “长”

函数名的核心是 “说明它做什么”，而不是 “它是什么类型”。很多新手怕函数名太长，用func1、do_something这类泛泛的名字，反而增加理解成本 ——清晰比简短更重要。

❌ 反面示例：

# 问题：func1做什么？需要读函数内部代码才知道
def func1(data):
    return [x for x in data if x > 60]

# 调用时一脸懵：传什么data？返回什么结果？
result = func1([85, 40, 72, 58])

✅ 正面示例：

# 优点：函数名直接说明“筛选列表中大于60的元素”
def filter_scores_above_60(scores):
    return [score for score in scores if score > 60]

# 调用时一目了然：传“分数列表”，得“及格分数”
passed_scores = filter_scores_above_60([85, 40, 72, 58])
print(passed_scores)  # 输出：[85, 72]

3. “三不要” 原则（⚠️避坑指南）

除了 “要做什么”，更要明确 “不要做什么”—— 这些细节容易被忽略，却会让代码变得混乱。

3.1. 不要 “自造缩写”

缩写的目的是简化命名，而不是制造 “密码”。如果你的缩写只有自己能懂，团队其他人需要花时间猜测，就失去了意义。必须使用行业或 python 社区通用的缩写。

❌ 反面示例（自造缩写）：

# 问题：nm和thrs是什么？第一次接触代码的成员可能看不懂

nm: str = 'lyle'
thrs: float = 30.0  # 自造：thrs=threshold
pwd = "123456"   # 自造：pwd=password（虽常见，但建议写全password更清晰）

✅ 正面示例（通用缩写）：

# 通用缩写：id（identity）、url（uniform resource locator）、http（hypertext transfer protocol）

user_id: str = "1001"
user_password: str = "123456"  # 密码建议写全，避免歧义
config_path: str = "config.ini"

# 复杂场景可用通用缩写（如api、sdk）
api_key: str = "abc123def456"
sdk_version: str = "3.8.0"

3.2. 不要忽略 “英文语法”，注意单复数、动名词

变量名的语法错误会传递错误信息 —— 比如用单数表示 “多个元素”，用名词表示 “一个动作”，都会误导。

❌ 反面示例（语法错误）：

# 问题1：user存的是列表（多个用户），却用单数
user = ["lyle", "tom", "jerry"]
print(f"用户数量：{len(user)}")  # 逻辑上没问题，但语法误导

# 问题2：get_user是“获取用户”的动作，却用来存“用户信息”（名词）
get_user = "tony"

# 问题3：calculate_total是动词短语，却用来存“结果”（名词）
calculate_total = 1500  # 实际是“总金额”

✅ 正面示例（语法正确）：

# 规则1：单数表“单个”，复数表“多个”
users = ["lyle", "tom", "jerry"]  # 列表用复数
print(f"用户数量：{len(users)}")

# 规则2：变量用“名词”，函数用“动词/动名词”（表动作）
user_info = "tony"  # 变量：名词（用户信息）
total_amount = 1500  # 变量：名词（总金额）

# 规则3：函数用“动词开头”（如get_、filter_、calculate_）表动作
def get_user_info(user_id):  # 函数：动词（获取用户信息）
    return f"用户id {user_id} 的信息"

3.3. 不要 “滥用下划线”，避免过长或冗余

下划线是 python 推荐的 “蛇形命名法”（snake_case）的核心，但不是越多越好。冗余的下划线会让变量名变长，反而降低可读性。

❌ 反面示例（滥用下划线）：

# 问题1：冗余的“_of”“_for”，可简化
user_name_of_student = "lyle"  # 简化为 student_name
score_list_for_math = [90, 85, 92]  # 简化为 math_scores

# 问题2：无意义的前缀，增加长度
var_user_age = 20  # 前缀var_毫无意义，直接用user_age
data_order_total = 300  # 前缀data_冗余，直接用order_total

✅ 正面示例（简洁合理）：

student_name = "lyle"
math_scores = [90, 85, 92]
user_age = 20
order_total = 300

4. qa

4.1. 变量名用 “蛇形命名法” 还是 “驼峰命名法”？

python 官方推荐蛇形命名法（snake_case，全小写 + 下划线分隔），适用于变量、函数、模块；而驼峰命名法（camelcase，首字母大写）主要用于类名（如userinfo、studentscore）。

示例：

# 蛇形命名法（变量、函数）
user_address = "北京市朝阳区"
def calculate_discount(price):
    return price * 0.8

# 驼峰命名法（类名）
class userinfo:
    def __init__(self, name, age):
        self.name = name
        self.age = age

4.2. 什么时候用 “单下划线开头” 的变量（如_user_name）？

这是 python 的 “约定俗成”，表示该变量是 “内部变量”，不建议外部直接访问（类似其他语言的 “私有变量”）。虽然语法上不强制限制，但能提醒其他开发者 “不要随便修改”。

示例：

class student:
    def __init__(self, name, score):
        self.name = name  # 公开变量，外部可访问
        self._score = score  # 内部变量，建议外部通过方法访问
    
    # 外部通过这个方法获取分数，而不是直接访问_score
    def get_score(self):
        return self._score

4.3. 变量名太长怎么办？

比如有一个变量的名称为calculate_monthly_user_payment_total。

首先，“长” 不是问题，“不清晰” 才是问题。如果确实过长，可以通过以下方式优化：

检查是否有冗余词（如calculate可简化为calc，但需团队认可）；
拆分逻辑（比如将复杂计算拆成多个小函数，变量名自然简化）。示例优化：

tip：apple公司的变量名和函数名都非常长，但却得到很多人的认可

# 原长变量名
calculate_monthly_user_payment_total = 5000

# 优化：拆分逻辑，变量名更简洁
def calc_user_payment(monthly_fee):
    return monthly_fee * 12  # 假设年付是月付的12倍

user_yearly_payment = calc_user_payment(5000)  # 简化为“用户年付款”