Python：命名约定

在 Python 编程中，命名约定（Naming Conventions）提高代码可读性与可维护性的关键。

合理的命名不仅让代码符合团队规范，还能避免歧义与冲突。

Python 官方文档和 PEP 8（Python 官方代码风格指南） 提供了一系列通用规则，同时社区也形成了一些惯例。

一、总体原则

1、可读性优先

名字应当简洁、明确，做到“见名知义”。

2、一致性

团队或项目应当统一命名风格，不要混用。

3、避免冲突

不要随意使用 Python 保留字或与内置函数重名（如 list, str, id）。

# 不推荐：覆盖了内置 list 类型
list = [1, 2, 3]
print(list)        # [1, 2, 3]
print(type(list))  # → 实际已丢失对内置 list 的引用

二、不同对象的命名风格

1、变量与函数

使用全小写字母，单词之间以下划线分隔。

这种风格称为“蛇形命名”（snake_case）。

user_name = "Alice"
max_length = 100

def calculate_area(radius):
    return 3.14 * radius * radius

2、常量

使用全大写字母，单词之间可以以下划线分隔。

常量通常放在模块的顶部。

PI = 3.14159
MAX_CONNECTIONS = 100

3、类与异常

每个单词首字母大写，不使用下划线。异常类名通常以 Error 结尾。

这种风格称为“大驼峰命名”（PascalCase）。

class Person:
    pass

class ValidationError(Exception):
    pass

4、模块与包

推荐使用简短的小写字母，必要时用下划线分隔。

例如：mathutils.py, data_loader/ 等。

math_utils.py
data_loader/

5、特殊方法与特殊属性

同时以双下划线开头和结尾的命名（__xxx__），保留给 Python 内部使用。这些被称为特殊方法（“魔术方法”）和特殊属性。

如 __init__(), __len__(), __str__() 以及 __name__ 等。

class Demo:
    def __init__(self):
        self.value = 0

    def __str__(self):
        return f"Demo(value={self.value})"

__all__ = ["connect", "disconnect"]  # 控制模块导出接口        

注意：

不要自定义不在规范内的名字，如 __myfunc__。

三、有关下划线的特殊约定

1、前置单下划线：_name

约定俗成表示“内部使用”或“受保护属性”。

不会真正阻止外部访问，只用于提示“请勿直接使用”。

class Person:
    def __init__(self, name):
        self._name = name   # 内部属性

在数据描述符中，常用 "_name" 作为实例字典的存储键，避免与类属性冲突。

class Descriptor:
    def __get__(self, instance, owner):
        return instance.__dict__["_value"]
    def __set__(self, instance, value):
        instance.__dict__["_value"] = value

2、前置双下划线：__name

前置双下划线且无后置双下划线，这将触发（name mangling），解释器会将其改为 _类名__name。

常用于避免子类覆盖父类属性。

class A:
    def __init__(self):
        self.__secret = 42

print(A().__dict__)  # {'_A__secret': 42}

3、后置单下划线：name_

当名字与保留字冲突时，可以加一个下划线。

class_ = "Math"
id_ = 42

4、单下划线：_

在交互式环境中，_ 常表示上一次运算结果。

>>> 5 + 6
11
>>>_ + 4
15

在循环或解包中，_ 常作为占位符，表示“不关心的值”。

for _ in range(5):
    print("Hello")

a, _, b = (1, 2, 3)  # 忽略第二个值

四、团队与项目的命名策略

1、统一规范

建议团队写一份代码风格指南（参考 PEP8、Google Style Guide）。

2、自动化检查

使用工具如 、、 等，自动检测和格式化代码。

3、一致性大于完美

与其在风格选择上争论，不如保持整个项目一致。

4、命名空间设计

在大型项目中，合理的包结构和模块划分也是命名策略的重要组成部分。

小结

Python 社区的基本规范来自 PEP 8：

变量/函数 → 蛇形命名（snake_case）

类/异常 → 大驼峰命名（PascalCase）

常量 → 全大写字母（UPPER_CASE）

模块/包 → 全小写（lowercase）

下划线约定：

_name → 内部使用

__name → 名称改写（避免子类冲突）

_ → 占位符或交互式结果

name_ → 避免与保留字冲突

合理使用命名约定，可让 Python 代码更清晰、专业、易维护。

“点赞有美意，赞赏是鼓励”