Python 命名规范

Python 命名规范（PEP 8 + 社区最佳实践）

遵循统一的命名规范可以提高代码可读性、可维护性，并减少潜在的错误。本文基于 PEP 8 和 Python 社区的最佳实践，总结了 Python 代码中的命名规则。

1. 变量命名

  • 风格：snake_case（小写字母 + 下划线分隔单词）
  • 示例：
    1
    2
    3
    user_name = "Alice"
    max_count = 100
    total_price = 199.99

2. 函数命名

  • 风格：snake_case
  • 示例：
    1
    2
    3
    4
    5
    def calculate_total():
        return 42

    def get_user_data():
        return "Alice"

3. 类命名

  • 风格：PascalCase（首字母大写，每个单词首字母均大写）
  • 示例：
    1
    2
    3
    4
    5
    class Person:
        pass

    class DataProcessor:
        pass

4. 常量命名

  • 风格：UPPER_SNAKE_CASE（全大写，单词间用 _ 连接）
  • 示例：
    1
    2
    3
    MAX_SIZE = 1000
    PI = 3.14159
    DEFAULT_TIMEOUT = 30

5. 模块（文件）命名

  • 风格：小写字母，尽量避免 _，仅在必要时使用 _。

  • 示例：

    1
    2
    mymodule.py   ✅ 推荐
    my_module.py  ✅ 可行（避免冲突时）

  • 错误示例：

    1
    2
    MyModule.py   ❌ 不推荐（首字母大写）
    my-module.py  ❌ Python 不支持 `-` 作为 import 语法

6. 包（文件夹）命名

  • 风格：小写字母，单词用 _ 分隔（不能使用 -）

  • 示例：

    1
    2
    3
    my_package/
        __init__.py
        data_loader.py

  • 错误示例：

    1
    my-awesome-package/  ❌ Python 代码不能用 `-`

7. 方法命名（类中的函数）

  • 风格：snake_case
  • 示例：
    1
    2
    3
    class User:
        def get_full_name(self):
            return "Alice Smith"

8. 私有变量和方法

8.1. 约定为私有

  • 风格：_single_leading_underscore
  • 作用：表示该变量或方法是内部使用的（但仍可访问）
  • 示例：
    1
    2
    3
    4
    5
    6
    class Example:
        def __init__(self):
            self._internal_variable = 42  # 约定为私有

        def _helper_function(self):
            pass  # 约定为私有

8.2. 避免子类覆盖（名称改编）

  • 风格：__double_leading_underscore
  • 作用：Python 会进行名称改编（Name Mangling），避免子类覆盖
  • 示例：
    1
    2
    3
    4
    5
    6
    7
    8
    9
    class Example:
        def __init__(self):
            self.__private_variable = 99  # 触发名称改编

        def __private_method(self):
            pass  # 触发名称改编

    obj = Example()
    print(obj._Example__private_variable)  # 可以访问，但不建议

9. 特殊变量和方法（Dunder Methods）

  • 风格：__double_underscore__（前后双下划线）
  • 作用：Python 内置的特殊方法，定义对象行为
  • 示例：
    1
    2
    3
    4
    5
    6
    7
    8
    9
    class Person:
        def __init__(self, name):
            self.name = name

        def __str__(self):
            return f"Person: {self.name}"

        def __repr__(self):
            return f"Person({self.name!r})"

10. 文件和文件夹命名

  • 文件名：snake_case.py
  • 包名（文件夹）：snake_case
  • 示例：
    1
    2
    3
    my_project/
        data_processing.py
        utils/

11. 工程名（项目名）

11.1. 代码仓库（GitHub/GitLab）

  • 风格：推荐使用短横线 - 分隔单词
  • 示例：
    1
    2
    awesome-tool/    ✅ 推荐
    deep_learning_tool/  ✅ 可行

11.2. Python 包（import 时）

  • 风格：snake_case（小写 + _）
  • 示例：
    1
    import my_package

11.3. PyPI 发布的包（pip install 时）

  • 风格：短横线 -
  • 示例：
    1
    pip install my-awesome-package

12. 避免使用的命名

12.1. Python 关键字

  • 错误示例：
    1
    class = "hello"  ❌ 不能使用 `class`

12.2. Python 内置函数

  • 错误示例：
    1
    2
    list = [1, 2, 3]  ❌ 覆盖了 Python 内置 `list()`
    print(list([4, 5, 6]))  # TypeError

12.3. Python 标准库模块

  • 错误示例：
    1
    json.py   ❌ 可能导致 `import json` 失败

总结

类别 命名风格 示例
变量、函数、方法 snake_case（小写+下划线） total_amount = 100
类名 PascalCase class MyClass:
常量 UPPER_SNAKE_CASE MAX_SIZE = 100
模块（文件名） snake_case.py import my_module
包（文件夹名） snake_case import my_package
私有变量/方法 _single_leading_underscore _internal_var
避免子类覆盖 __double_leading_underscore __private_var
特殊方法 __dunder__（Python 内置方法） __init__, __str__
代码仓库（GitHub） kebab-case（短横线 -） my-project/
PyPI 包名 kebab-case（短横线 -） pip install my-package

结论

  1. 遵循 PEP 8 规范，代码更加清晰、可读、易维护。
  2. 不同环境使用合适的命名风格，避免命名冲突。
  3. 变量、函数、方法使用 snake_case，类使用 PascalCase，常量使用 UPPER_SNAKE_CASE。
  4. 模块和包使用 snake_case，但 PyPI 包和 GitHub 仓库使用 kebab-case。

🚀 遵循这些命名规则，让你的 Python 代码更加 Pythonic！