17370845950

函数应单一职责、命名精准、依赖隔离、类型明确：只做一件事且能一句话说清；命名用动宾结构体现行为与依据；不直接调用I/O，通过参数注入依赖；用类型提示和docstring声明契约。

函数职责清晰，核心是“一个函数只做一件事”，并且这件事要能用一句简洁的话说清楚。不是看代码行数多少，而是看它是否混杂了不同层次的逻辑、不同领域的操作，或者承担了本该由其他函数或模块处理的任务。

聚焦单一行为，避免功能堆砌

比如一个函数既要读取配置文件、又要解析 JSON、还要校验字段、最后返回连接参数——这其实包含了 I/O、数据解析、业务校验三个职责。应拆成 load_config()、parse_config()、validate_co

• 输入参数只接收完成该任务必需的数据，不传“大对象”或“上下文容器”来塞一堆可能用不到的字段
• 函数体内不出现条件分支去处理完全不同的业务场景（如 if mode == "fast": ... else: ...），那是调用方该做的决策
• 返回值类型稳定，避免有时返回字典、有时返回 None、有时抛异常——统一用返回值表达成功，异常只表示真正意外的错误

命名即契约，让名字说出它的全部责任

函数名不是动词短语拼凑，而是对职责的精确声明。看到 calculate_discounted_price() 就知道它只算价格，不发通知、不更新库存、不记录日志。如果发现需要加“and”才能说清职责（如 save_user_and_send_welcome_email()），说明它已经越界。

• 优先用动宾结构：fetch_user_by_id() 比 get_user() 更明确作用域和依据
• 避免模糊词：不用 process()、handle()、do_something()，它们掩盖了真实意图
• 若函数只做副作用（如写日志、发请求），名字要体现这一点：log_payment_success() 而非 payment_success()

隔离外部依赖，把“怎么做”交给调用方

清晰职责的前提是边界干净。函数内部不应直接调用 requests.get()、open() 或数据库连接——这些属于实现细节，会污染职责纯度。改为接收已准备好的数据，或通过参数注入依赖。

• 把 I/O 结果作为参数传入：def validate_order(order_data: dict) -> bool:，而不是在函数里自己读文件
• 用可调用对象或协议类封装外部行为：def send_notification(notifier: Notifier, message: str)，便于测试和替换
• 不隐藏状态变化：如果函数修改了传入对象，名字中需体现（如 mutate_user_permissions()），否则默认应保持不可变性

用类型提示和文档强化契约意识

类型提示不只是给编辑器看的，它是职责的静态说明书。加上 -> list[Product] 就锁定了输出结构；标注 user_id: int 就排除了字符串 ID 的歧义。配合简洁的 docstring，三句话讲清“做什么、输入什么样、输出什么样”，比写十行注释更有效。

• 类型提示覆盖所有参数、返回值、关键局部变量（尤其涉及 union 或复杂嵌套时）
• docstring 不解释“怎么实现”，只说明“能干什么”和“什么情况下会失败”
• 对空输入、边界值、异常输入的行为有明确约定，比如 None 输入是报错还是返回默认值，写进文档而非靠猜

不复杂但容易忽略：职责清晰不是一开始就能设计完美，而是在每次新增逻辑、每次重构时多问一句——“这件事真的属于它吗？”