python函数名命名规范PEP8怎么写

在 Python 官方编码规范 PEP 8（Style Guide for Python Code）中，函数名的核心要求非常明确：全部使用小写字母，单词之间通过下划线（_）进行连接，这种写法在业界被称为蛇形命名法（snake_case 或 lowercase_with_underscores）。对于需要限定可见性的内部函数，通过在最前端增加单下划线或双下划线加以区分。

一、PEP 8 核心基本形式：小写加下划线

打开官方 PEP 8 规范的“Naming Conventions（命名约定）”一章，在“Function and Variable Names（函数与变量名）”小节中，第一句话给出的标准即为：

"Function names should be lowercase, with words separated by underscores as necessary to improve readability."（函数名应当全小写，必要时单词之间以下划线分隔以提升可读性。）

之所以选用下划线蛇形分割，是因为全小写配合下划线在视觉上保持水平基线一致，既避免了多单词粘连造成的辨识困难，又不会因为大写字母突兀跳跃而打断视线。

1. 动宾搭配与自解释原则

函数在程序中代表一种“动作”或“计算行为”。编写函数名时，通常应当遵循动词 + 业务对象名词的动宾结构，让调用者仅通过函数名字就能准确预测其行为职责，无需频繁翻查函数体内的代码实现。

# 标准推荐：动词 + 业务名词
def calculate_total_amount(unit_price: float, quantity: int) -> float:
    return unit_price * quantity

def fetch_user_profile(user_id: int) -> dict:
    return {"user_id": user_id, "status": "active"}

def send_alert_email(recipient: str, message: str) -> bool:
    print(f"向 {recipient} 发送预警邮件: {message}")
    return True

反之，如果函数名只写名词（如 def user()）或者只写无指向的动词（如 def handle()），就会大幅增加阅读成本，导致函数职责含糊不清。

二、不同作用域下的下划线使用约定

除普通的公开函数外，在编写模块辅助逻辑、类方法或面向对象继承体系时，PEP 8 通过下划线前缀约定了不同的可见性层次。

1. 单下划线前缀（_single_leading_underscore）

用于标识“内部使用（Non-public / Internal）”的函数或方法。这是一种弱内部保护约定：它向开发者表明该函数是模块或类的实现细节，随时可能被重构，不建议外部调用方强行依赖。

在模块级别，以单下划线开头的函数在被其他文件使用 from module import * 导入时会被自动忽略，不会污染导入者的命名空间。

# helpers.py 内部辅助函数
def _clean_raw_payload(payload: str) -> str:
    """内部清洗函数，不作为公共 API 暴露给外部模块"""
    return payload.strip().lower()

def process_request(raw_data: str) -> dict:
    """公开接口函数"""
    cleaned = _clean_raw_payload(raw_data)
    return {"result": cleaned}

2. 双下划线前缀（__double_leading_underscore）

用于类内部的方法命名。以双下划线开头（且末尾最多一个下划线）的方法会触发 Python 解释器的名称修饰机制（Name Mangling）。解释器会自动在名称前加上 _ClassName 前缀（例如 __update_cache 会被重写为 _MyClass__update_cache）。

这样做的核心目标不是为了“绝对私有不可访问”，而是为了防止子类在继承时无意中重写（Override）父类的内部关键逻辑，从而产生难以排查的父子类同名方法冲突。

class BaseWorker:
    def __init__(self):
        self.__setup_connection()

    def __setup_connection(self):
        # 解释器将其改写为 _BaseWorker__setup_connection
        print("初始化底层网络连接")

class CustomWorker(BaseWorker):
    def __setup_connection(self):
        # 解释器改写为 _CustomWorker__setup_connection，不会无意覆盖父类的实现
        print("子类自定义连接设置")

3. 双下划线首尾（__magic_method__）

形如 __init__、__str__、__call__ 的名称被称为特殊方法或魔法方法（Magic Methods / Dunder Methods）。PEP 8 明确规定：这类命名空间由 Python 核心团队统一保留与规划，普通开发者永远不要自行创造首尾双下划线的自定义函数名，以防未来与 Python 新版本引入的系统级协议发生命名冲突。

三、常见语义场景的具体命名规范

编写实际工程代码时，不同返回特性和功能目标的函数往往有约定俗成的专用词汇组合：

• 返回布尔值的谓词函数：推荐以 is_、has_、can_、should_ 开头。例如 is_valid_email()、has_permission()、can_retry()。调用时代码读起来如同自然问句（例如 if is_valid_email(user_email):）。
• 数据形态转换函数：推荐使用 to_ 或 as_ 连接目标类型。例如 to_dict()、as_dataframe()、parse_json_string()。
• 资源生命周期管理：成对出现的动词需保持对称。如 open_file() / close_file()、acquire_lock() / release_lock()、start_service() / stop_service()。

四、必须避开的高频红线与冲突

编写函数名时，有两类典型问题最容易在团队协作中引入隐患：

1. 遮蔽 Python 内置函数与关键字（Shadowing Built-ins）

Python 拥有诸如 list、dict、str、type、id、filter、map、max、min、sum 等丰富的内置函数与类型。如果不小心将自定义函数命名为 filter 或 list，该名称在当前作用域内就会覆盖 Python 原生对象，导致后续试图使用原生内置功能的代码发生报错。

2. 风格混杂与大驼峰污染

来自 JavaScript、Java 或 C# 背景的开发者常常不自觉地使用小驼峰（calculateTotalPrice）。PEP 8 虽提到在兼容老旧代码库（如 Python 标准库早期引入的 threading.py）时允许保留驼峰以向下兼容，但在所有全新编写的 Python 3 代码中，均应坚决使用小写加下划线。

同时，首字母大写的驼峰（PascalCase 或 CapWords）是 PEP 8 中类名（Class Name）的专属格式。如果将普通函数命名为 CalculateTax()，阅读者会误认为这是一个正在实例化的类对象。

五、工程化落地：使用静态检查工具自动校验

在实际项目维护中，无需完全依赖人工记忆规则。我们可以借助现代 Python 静态检查工具，在提交代码时自动发现不符合 PEP 8 的函数命名。

例如编写一个包含驼峰命名的测试文件 test_demo.py：

# test_demo.py 示例代码
def calculateTotalPrice(price: float, tax: float) -> float:
    return price * (1 + tax)

使用当下主流的代码检查工具 flake8 或 ruff 执行检查：

# 使用 ruff 检查函数命名规则（N802 代表函数名应当全小写）
ruff check test_demo.py --select N802

工具会精准定位到第 1 行第 5 列，明确指出函数名应当为 lowercase。将名称修正为 calculate_total_price 即可顺利通过检查。

六、总结速查

撰写符合 PEP 8 规范的 Python 函数名，可以提炼为以下三条黄金准则：

1. 基本格式咬死蛇形：无论函数名称长短，一律采用纯小写字母搭配下划线（snake_case）。
2. 语义结构首选动宾：以体现行为的动词引导，搭配明确的业务对象（如 get_user_by_id），布尔返回用 is_ / has_。
3. 作用域修饰按需添加：模块或类内部私有用单下划线（_helper），避免子类冲突才用双下划线（__mangled），严禁随意发明首尾双下划线魔法名。