1. 命名规范这件事为什么值得单独写一篇我在帮团队做代码评审的时候见过太多让人挠头的名字。有的是拼音和英文混搭比如zhanghu_info有的是缩写到亲妈都认不出来比如cs2还有的把类型塞进名字里比如list_temp。每次我都得对着变量名猜半天它到底是干嘛的这比看复杂算法还累。其实 Python 官方早就把规则写在 PEP 8 里了但问题是真到了写业务代码的时候很少有人会翻文档。而且命名规范不只是“变量用小写下划线”这种表面功夫它背后还牵扯到代码可读性、团队协作效率、甚至是后续重构的改造成本。这篇文章我打算把 Python 命名规范从“背规则”上升到“理解规则为什么存在”再结合我实际写代码、做评审、带新人过程中的经验聊点文档里不会细讲的东西。适合什么人看刚入门 Python 的初学者能把基础规范一次理清写了两三年代码但没认真抠过命名细节的人能补上容易被忽略的坑带团队、做代码审查的人可以参考后面提到的落地经验。总之这篇文章的目标是让“起名”这件事变得不纠结。2. 底层逻辑命名规范解决的不是审美问题是信息传递问题2.1 代码首先是给人读的其次才是给机器跑的这一点算老生常谈但我还是想换个角度说。机器的理解能力几乎不受变量名影响——你在 Python 里写a 1还是user_count 1最终编译出来的字节码性能差异可忽略不计。真正受影响的是下一位读代码的人而这个人有极大概率就是三个月后的你自己。我见过不少项目为了“短”而刻意用单字母变量一开始写的人觉得爽等到要排查线上问题时满屏的a、b、x会让你怀疑人生。人的短期工作记忆容量有限看代码时脑子里同时要维护的东西本来就多名字再不给点暗示读代码的速度会断崖式下跌。打个比方命名规范就像快递柜上的编号如果一个格子写“3号”另一个格子写“放冬衣的大格子”你用脚趾头想都知道哪个好找。2.2 规范的共识价值大于规范本身有人会问PEP 8 里说的就全对吗我跟你说不完全对每个团队都有自己的习惯但有一件事是确定的——一旦团队确定了某种写法全体都按这个来收益远大于某个写法单独看是否“最优”。举例来说有些老项目里会出现匈牙利命名法的残留变量名前加类型前缀比如strName、intCount这在 Python 社区里其实不被推荐。但如果整个团队都这么写彼此也能看懂那它的坏处就没有想象中那么大。最怕的是团队里一半人用snake_case另一半人用camelCase同一个变量有时叫userName有时叫user_name那才是真正的灾难。所以我在给团队定规范的时候最常强调的一句话是规范要解决的第一个问题是“统一”第二个问题才是“合理”。你先跟大家约定好一套规则再根据项目实际情况微调这比一边写一边纠结“哪个更 Pythonic”靠谱得多。3. Python 命名规范的实用框架从实体类型出发3.1 五种基础命名形式先搞清楚长什么样Python 里的命名形式主要分这么几类我整理了一个速查表命名形式示例主要用途snake_case小写下划线user_name、get_order变量名、函数名、模块名PascalCase大驼峰UserProfile、OrderService类名UPPER_CASE全大写加下划线MAX_RETRY_TIMES、DEFAULT_PORT常量单下划线前缀_private_value、_internal_method模块内部私有成员双下划线前后包裹__init__、__str__Python 内置特殊方法dunder方法很多初学者搞不清_private和__private双下划线但不能以后缀结尾的区别。简单说单个下划线开头是“君子约定”表示这个成员是内部使用的你非要访问也能访问只是不合适双下划线开头会触发 Python 的名称改写机制name mangling在类外部直接按原属性名访问会报错这已经算有强制力了。举个小例子你有这样一个类class User: def __init__(self, name): self._name name # 约定私有外部能访问 self.__token abc # 改名后变成 _User__token在外部代码里user._name能取到值虽然不提倡但user.__token会报 AttributeError如果你想强行访问得写成user._User__token。这个机制本意是防止命名冲突不是用来做严格的数据封装的但很多新手误以为双下划线是“私有属性”的标准写法这里得校正一下。3.2 各实体命名速查变量、函数、类、常量、模块变量名用小写单词加下划线比如item_count、last_login_time。如果变量名只有一个单词直接用count也可以不要为了凑 snake_case 硬把单词拆开。函数名同样用 snake_case通常以动词开头让人一看就知道它做什么例如get_user_by_id、send_email_notification。这里有一个经常被忽略的点函数名不要太长超过了四五个单词就得怀疑是不是职责拆得太粗考虑把它拆成更小的函数。类名用 PascalCase名词为主。比如OrderManager、HttpClient。类名相当于一种类型标签用名词符合直觉。特别提醒类名不要包含“Impl”“Helper”这种后缀太多这类名字说明设计上可能有问题后面我会展开。常量用全大写加下划线例如DEFAULT_TIMEOUT 30。常量的特点是全局不会变它不是“程序运行期间值不变”而是“逻辑上不应改动”的值。像MEI_TUAN_API_BASE_URL这种项目级的配置类常量也归到这一类。模块名应该简短全部小写尽量不用下划线或只用少量下划线。比如utils.py、http_client.py。如果你发现模块名忽长忽短说明包的边界划分有问题。3.3 为什么“不要用单字母变量名”这句话不是绝对真理网上很多教程说“禁止单字母变量名”这其实有点矫枉过正。在局部且上下文极短的循环里用for i in range(10)完全没问题硬改成for index in range(10)反而显得啰嗦。但是如果单字母变量出现在函数参数、类的属性、甚至模块级变量的位置上那基本就是可读性灾难。我评审代码时通常按这个标准判断变量作用域超过 10 行就必须给它一个有意义的名字。还有一种情况一个函数里连续出现a、b、c三个单字母变量那基本可以直接打回。另外值得提的是下划线_的两种常见用法。第一种是用来占位表示“这个位置有值但我不关心”比如解包时_, b some_tuple第二种是循环次数占位比如for _ in range(5)。此外在交互式解释器里_代表上一次表达式的结果在 gettext 国际化的场景里_()代表翻译函数。这个符号看似简单但在不同上下文里的语义完全不同你读代码时得注意区分。4. 容易被忽略但极其重要的命名细节4.1 私有成员下划线规则的本质是“信任边界”前面我提了单下划线和双下划线这里再深入讲讲。Python 没有真正的私有概念这是它的设计哲学——它信任开发者不做强制护栏。所以_attr这种写法本质上是“大家说好不要碰”属于君子协定。很多从 Java、C 转过来的程序员会浑身不自在觉得没有 private 关键字就跟没穿裤子一样。但实际用下来你会发现这种宽松反而促进了 Python 生态里“面向接口而非实现”的开发习惯——你更多是信任约定而不是依赖语言强制的封装。至于双下划线__attr它的 name mangling 机制除了防冲突还有另一个隐藏用途——让子类可以安心定义自己的同名属性而不会被父类的内部属性意外覆盖。举个例子class Parent: def __init__(self): self.__value 1 class Child(Parent): def __init__(self): super().__init__() self.__value 2 # 不会覆盖父类的 _Parent__value这个场景在写框架代码时很实用。但是说实话绝大多数业务代码根本用不到双下划线开头的属性如果你想表达“内部实现细节”一个下划线就够了如果想防继承冲突再考虑双下划线。4.2 双下划线前后包裹的名称dunder是协议不是魔法__init__、__len__、__repr__这些前后双下划线的名字常被新手指“魔法方法”的标签误导仿佛是什么神秘力量。其实它们的本质是要让自定义对象和 Python 内置语法/内置函数对齐——让对象能支持加法、求长度、被打印时显示特定格式等等。它们不是魔法Python 内部在实现len(obj)时做的事情本质上就是在调用obj.__len__()。命名规范里要记住的是永远不要为了“看起来厉害”而自己发明__xxx__名字。Python 的 dunder 方法名是语言协议的一部分瞎定义一个__get_user__不会产生任何魔法效果只会让读代码的人困惑。如果你真想定义“内部方法”用一个下划线前缀就够。4.3 类型占位符与类型提示命名的另一个维度TYPE_CHECKING和TypeVar看着可能有点远但 Python 3.5 的类型提示体系里也有命名约定。比如自定义 TypeVar 时习惯用一个简短大写的名字from typing import TypeVar T TypeVar(T) UserId TypeVar(UserId, boundint)T、K、V这些短名字是社区默认的泛型占位符当你看到def first_element(items: List[T]) - T时不用纠结T没有具体含义它就是“某种类型”的符号。再比如cast(Any, value)这种写法里Any的语义是“任意类型”这不算坏命名。类型提示的命名可以适度宽松但核心目标还是清晰表达“这个变量到底是什么类型、什么语义”不能因为披了类型提示的皮就把变量名写得乱七八糟。4.4 不要与内置类型“撞车”Python 有很多内置名字list、dict、str、int、set、sum、min、max甚至id、type。一旦你把变量命名为list在当前作用域内list()就被你覆盖了后面想构造列表就得绕道。这个错误太常见了我给你看个典型def get_names(users): list [] # 大忌 for user in users: list.append(user[name]) return list代码跑起来没问题但过几天你想在这函数里调用内置list()时就会踩到一个诡异异常。正确的做法是用name_list、names、user_names这类能表达语义的名字既避免了保留字冲突又增加了信息量。5. 动手实践从命名到落地的几个关键环节5.1 重新设计一个类的命名我把思考过程拆给你看光讲理论容易飘我拿一个实际场景做例子。假设要写一个订单系统初期有人写出了这样的代码class order: # 类名用 snake_case不合格 def __init__(self, id, buyer_id): self.id id self.buyer_id buyer_id def check(self): # 太笼统 pass def getdata(self): # 动词和名词都含糊 pass我们来逐步优化。首先类名order改为Order符合 PascalCasecheck改成is_valid或者has_enough_stock具体看业务逻辑动词要精准getdata这种“数据”边界模糊的命名拆成get_items、get_discount等明确职责的方法。最终形态大致是class Order: def __init__(self, order_id: int, buyer_id: int): self.order_id order_id self.buyer_id buyer_id self._items [] def total_amount(self) - float: ... def add_item(self, sku_id: int, quantity: int) - None: ...从这个例子里你能看出一个规律好的命名往往意味着类和方法职责更清晰。如果你发现某个方法名怎么起都别扭多半是这个方法本身干了太多事。5.2 代码审查时我会按什么顺序检查命名做代码审查时我有一套固定的检查顺序。先看模块和包的名字是否与业务模块对应再看类名是否符合单一职责接着看公开方法的名字是否看起来像“对外承诺”一旦有人调用它改名就是伤筋动骨然后是变量名重点看函数内部的局部变量是否有意义最后才检查注释和 docstring是否过时。这套顺序帮你把握了优先级越靠近“对外接口”的命名越要谨慎。内部实现里某个局部变量叫tmp其实可以接受但一个公开函数的参数如果叫a、b那基本会被我打回。5.3 团队落地先定“命名契约”再谈代码审查很多团队不是不知道 PEP 8也不是不知道命名规范问题是写代码的和审代码的对规范的理解不一致。我建议每个团队都整理一份“命名契约”不需要长几页就行但必须有实际案例对比。比如在契约里直接写明变量snake_case 命名禁止类型前缀类PascalCase 命名名词短语常量UPPER_CASE定义后不可修改私有成员以下划线开头TODO/FIXME 注释统一格式数据库列名与代码字段的映射关系避免“代码一个名、数据库一个名”有了这种东西新人入职后就能快速对齐代码评审时也有据可查。比“老员工口头讲、新人凭感觉猜”有效得多。6. 工具检查 避坑指南让规范自动挡在写代码的前面6.1 用 linter 和格式化工具把低级的命名问题直接干掉人工盯命名始终会有遗漏不如把规则交给工具。Python 生态里最常用的是flake8用来检查代码风格和命名方面的明显问题比如变量名不符合 snake_case、pylint能识别更多问题但默认规则偏严需要团队配置、black自动格式化虽然它不检查命名但能让代码风格统一以及isort自动整理 import 顺序。我自己在实际项目里的做法是black负责格式flake8负责拦截低级命名错误mypy负责类型层面的约束。三层下来基础的命名问题基本能挡在代码提交之前。但是注意了——工具能抓的是“明显不合规”抓不到“明显不合适”。比如tmp1、tmp2这种名字规则上挑不出毛病但语义上就是差劲。这种问题只能靠代码评审和个人意识解决。6.2 我总结的命名六宗罪碰到这些直接打回第一宗罪拼音命名。除非是专有名词比如taobao、wechat否则中文拼音做变量名会让非中文背景的协作者完全看不懂。第二宗罪没意义的缩写。cnt还能猜到是 countcs2这种就没法猜了。第三宗罪与类型“捆绑”。像list_data、str_name里的类型信息是冗余的变量应该描述语义而不是类型。第四宗罪过于笼统。data、info、result满天飞等于什么都没说。第五宗罪重复信息。user_list和users同时存在到底哪个是哪个应该只留一个。第六宗罪误导性命名。这个最坑别人叫is_active但代码里实际判断的是“未删除”这比没起名更致命。6.3 几个真实的踩坑实录我早年维护过一个项目有个变量叫time结果覆盖了time模块排查问题时想在日志里打一个当前时间写time.strftime()结果报 AttributeError卡了快两小时才意识到是自己的变量把模块遮蔽了。从那以后我再也不在业务代码里用模块名做变量名。还有一次团队里有人写了个函数叫save()同事听名字以为是保存数据到数据库一试才发现是保存配置到文件。函数名和实际行为不一致这种误导比注释写错还可怕。后来我们干脆在命名契约里加了一条硬规定函数的动词描述“它真正做的事”不许含混。关于集合类型的命名也常有分歧。有人喜欢用复数users有人喜欢用结尾user_list都说得通。我个人的建议是能追求自然语言的就用复数users明显比user_list更贴近英语直觉但如果是需要“有序序列”这个语义时可以显式加list后缀比如sorted_user_list这时后缀是在补充信息不算冗余。7. 放下纠结命名没有唯一答案但有一套可依的思维写到最后我想说点个人体会。很多人把命名当成“畏难之事”觉得“起个好名字好难”于是随手糊弄结果后面付出更高的维护成本。其实命名没有绝对的对错谈不上什么“最优解”——只要语义准确、风格统一、不过度冗余就是合格的名字。我自己在写代码时如果某个变量想了半天都想不到好名字通常不是词汇量不够而是代码结构出了问题。比如一个 getter 方法叫get_info你当然觉得别扭因为“info”太宽泛但如果你把方法拆成get_user_profile、get_order_status名字自然就出来了。命名困难往往是设计的报警器这大概是我这些年最大的体会。还有一个小技巧收尾给类属性起名字时试着用“名词短语”来写注释比如self._cache {} # 商品ID - 商品详情缓存。虽然这不是命名本身的要求但这种“名字注释一体”的习惯能让代码的可读性再上一层楼。我试过在团队里推广这个习惯效果意外地好——因为它强迫你在写完名字后的三秒内再用一句人话把名字的含义说清楚很多歧义在这个过程中就被消灭了。