Python 标识符命名：规则与最佳实践，写出优雅易维护的代码

标识符是 Python 编程的基础，它是变量、函数、类、模块等元素的名字。规范的命名不仅能让代码通过解释器的校验，更能大幅提升代码的可读性和可维护性。本文将系统梳理 Python 标识符的命名规则，并结合实战经验分享行业通用的最佳实践，帮助新手写出专业、优雅的 Python 代码。

一、Python 标识符命名核心规则（必须遵守）

Python 对标识符的命名有明确的语法规则，违反这些规则会直接导致SyntaxError，是每个 Python 开发者必须牢记的基础。

1. 合法字符范围

• 标识符由字母（A-Z/a-z）、数字（0-9）、下划线（_） 组成
• 首字符不能是数字（这是最常见的新手错误）
• 不能包含空格、特殊符号（如！、@、#、$、% 等）

错误示例：

python

运行

# 首字符为数字，报错
123name = "张三"  

# 包含特殊符号@，报错
user@name = "李四"  

# 包含空格，报错
user name = "王五"  

正确示例：

python

运行

# 合法标识符
name = "张三"
user_age = 20
_name = "私有变量示例"
Name123 = "混合数字"

2. 不能使用 Python 关键字

Python 的关键字（保留字）有特殊的语法含义，不能作为标识符使用。

可以通过以下代码查看 Python 所有关键字：

python

运行

import keyword
# 打印所有关键字
print(keyword.kwlist)

Python 3.x 常见关键字（如：if、else、for、while、def、class、import、return、True、False、None 等），例如：

python

运行

# 错误：使用关键字if作为变量名
if = 10  

# 正确：避开关键字
flag_if = 10

3. 大小写敏感

Python 标识符区分大小写，Name和name是两个完全不同的标识符：

python

运行

name = "小写"
Name = "大写"
# 输出：小写 大写（两个不同的变量）
print(name, Name)  

二、Python 命名最佳实践（建议遵守）

遵守语法规则是基础，而遵循命名规范则是专业的体现。Python 社区公认的命名规范主要参考《PEP 8》（Python Enhancement Proposal 8），以下是核心的最佳实践。

1. 不同元素的命名风格

表格

元素类型	命名风格	示例	说明
变量 / 函数 / 模块	蛇形命名法	user_name、get_user()	全小写，单词间用下划线分隔
类 / 异常	大驼峰命名法	UserInfo、FileError	每个单词首字母大写
常量	全大写 + 下划线	MAX_SIZE、PI	强调不可修改的常量
私有变量 / 函数	单下划线开头	_private_var	约定俗成的 “私有” 标识
魔术方法	双下划线包裹	init、str	Python 内置特殊方法
避免冲突的变量	单下划线结尾	class_、def_	避开关键字冲突

实战示例：

python

运行

# 常量：全大写+下划线
MAX_RETRY = 3
PI = 3.14159

# 变量：蛇形命名法
user_name = "小明"
user_age = 18
is_vip = True

# 函数：蛇形命名法+动词开头
def get_user_info(user_id):
    """获取用户信息"""
    return {"id": user_id, "name": user_name, "age": user_age}

# 类：大驼峰命名法
class UserProfile:
    # 私有变量：单下划线开头
    def __init__(self):
        self._user_score = 0
    
    # 魔术方法：双下划线包裹
    def __str__(self):
        return f"UserProfile(score={self._user_score})"

# 避开关键字冲突：单下划线结尾
class_ = "Python入门班"
def_ = "定义函数"

2. 命名的 “可读性” 原则

• 见名知意：拒绝无意义的命名（如 a、b、tmp1），用 “语义化” 的名字❌ 错误：x = 20、f1()✅ 正确：user_age = 20、calculate_total_price()

• 简洁且完整：避免过长或过短，平衡可读性和简洁性❌ 错误：u_a（过短）、the_age_of_the_current_login_user（过长）✅ 正确：user_age

• 统一命名风格：整个项目保持一致，不要混合蛇形和驼峰（如既有userName又有user_age）

3. 特殊场景的命名技巧

（1）私有元素命名

• 单下划线（_）开头：约定俗成的 “私有”，仅用于提示开发者（Python 不强制私有）
• 双下划线（__）开头：触发名称修饰（name mangling），避免子类覆盖父类属性（慎用）

python

运行

class Parent:
    def __init__(self):
        self._private = "单下划线（提示私有）"
        self.__mangled = "双下划线（名称修饰）"

class Child(Parent):
    def __init__(self):
        super().__init__()
        # 可以访问父类的单下划线属性
        print(self._private)
        # 无法直接访问双下划线属性（实际被修饰为_Parent__mangled）
        # print(self.__mangled)  # 报错
        print(self._Parent__mangled)  # 强制访问（不推荐）

（2）模块 / 包命名

• 模块名：全小写，简短，避免下划线（除非必要），如os、sys、user_auth
• 包名：全小写，无下划线，简洁，如myproject、utils

三、常见命名错误与避坑

1. 使用拼音 / 中英文混合：优先使用英文命名（如yong_hu_ming → user_name）
2. 滥用缩写：除非是行业通用缩写（如 ID、VIP、URL），否则不要随意缩写（如usr → user）
3. 命名与内置函数 / 模块冲突：避免使用list、dict、str、math等作为标识符

   python

   运行

   # 错误：覆盖了内置list类型
   list = [1,2,3]
   # 后续使用list()会报错：TypeError: 'list' object is not callable
   new_list = list()
   

4. 过度使用双下划线：仅用于魔术方法，日常开发优先用单下划线标识私有

四、工具辅助：自动校验命名规范

手动遵守规范容易出错，推荐使用工具自动校验：

1. pylint：检查代码风格（包括命名）

   bash

   运行

   pip install pylint
   pylint your_code.py
   

2. black：自动格式化代码（包含命名风格适配）

   bash

   运行

   pip install black
   black your_code.py
   

3. PyCharm/VSCode：编辑器内置命名规范提示，实时提醒不规范的命名

总结

1. 核心规则：标识符由字母 / 数字 / 下划线组成、首字符不能是数字、避开关键字、大小写敏感，违反会直接报错；
2. 最佳实践：变量 / 函数用蛇形命名、类用大驼峰命名、常量全大写，核心是 “见名知意、风格统一”；
3. 避坑要点：避免覆盖内置函数、不滥用缩写、优先用英文命名，可借助 pylint/black 工具辅助校验。

规范的命名是代码质量的第一道门槛，养成良好的命名习惯，不仅能让你的代码通过 Python 解释器的校验，更能让同事（甚至未来的自己）轻松读懂代码。从今天开始，拒绝 “随意命名”，写出专业、易维护的 Python 代码！