可读性

函数命名不是取名字：它是在描述系统边界 副标题： 好的函数名不只是“好听”。它应该让读者看出：这个函数在做读取、 解析、校验、筛选、创建，还是修改状态。 适读人群： 正在写 Python service、runner、pipeline、SDK 或业务模块的开发者 阅读时间： 8 min 背景：为什么 get_dependencies 不是总比 resolve_graph 直观？ 看一个小型 graph pipeline runner： def trigger(self, mode, context): dependencies = self._resolve_graph(mode) self._validate_graph(dependencies) record = self._create_graph_record(mode, dependencies, context) while True: ready_nodes = self._ready_nodes(record) if not ready_nodes: break for node_name in ready_nodes: ... 刚开始可能会问： 为什么不叫 get_dependencies？ 为什么不叫 get_handler？ 为什么 ready_nodes 没有动词？ 为什么 skip_dependents 一看就像会改状态？ 这些不是风格洁癖。函数命名背后其实是在表达系统边界： mode 是外部语言，graph 是内部执行结构。 handler name 是配置语言，handler 是可调用对象。 ready node 是运行时状态，不是普通列表。 skip dependents 是副作用，不是查询。 这篇文章用一个 pipeline runner 作为例子，讲清楚函数命名应该如何暴露设计意图。 ...

副标题 / 摘要 可读性强的代码不一定短，但必须降低认知负担。本文给出可执行的判断标准。 目标读者 参与代码评审的工程师 关注可维护性的团队 初中级开发者 背景 / 动机 代码的主要读者是人而不是机器。 可读性差会带来维护成本和错误风险。 核心概念 结构清晰：层次分明、职责单一 命名准确：表达意图而非实现细节 认知负担：阅读时需要记住的临时信息 实践指南 / 步骤 函数短小且单一职责 命名体现意图而不是过程 减少嵌套，提前返回 用测试与注释解释复杂逻辑 可运行示例 # 不好的命名 def f(x): return x * 1.08 # 更好的命名 def apply_tax(price): return price * 1.08 if __name__ == "__main__": print(apply_tax(100)) 解释与原理 读代码的时间通常远大于写代码。 清晰命名与结构能降低理解成本，减少错误。 常见问题与注意事项 注释能替代好命名吗？ 不能，注释是补充而不是替代。 缩短代码一定更好？ 不一定，过度压缩会降低可读性。 如何量化可读性？ 用评审与维护时间做间接衡量。 最佳实践与建议 在评审中强调命名与结构 复杂逻辑写成小函数 用一致的代码风格 小结 / 结论 可读性强的代码能降低认知负担，减少维护成本。 结构、命名与测试是三大关键。 参考与延伸阅读 Clean Code Code Complete 元信息 阅读时长：6~8 分钟 标签：可读性、代码质量 SEO 关键词：可读性, 命名 元描述：定义什么是可读性强的代码。 行动号召（CTA） 挑一段难读的代码，重命名并拆分后再做一次评审。

副标题 / 摘要 匿名函数让你在局部直接表达“临时逻辑”。本文解释它的工程价值，以及如何避免滥用。 目标读者 需要编写回调逻辑的开发者 使用多语言协作的工程师 追求可读性与简洁性的团队 背景 / 动机 很多逻辑只在一处使用，单独命名会带来额外噪音。 匿名函数能让代码更靠近语义，但也可能降低可读性。 核心概念 匿名函数（Lambda）：没有名字的函数表达式 回调：作为参数传入的函数 闭包：捕获外部变量的函数 实践指南 / 步骤 局部、小逻辑优先匿名函数 复杂逻辑必须命名 避免过度嵌套 捕获外部变量要明确 可运行示例 nums = [1, 2, 3, 4, 5] # 只使用一次的过滤逻辑 odds = list(filter(lambda x: x % 2 == 1, nums)) # 复杂逻辑用命名函数更清晰 def is_big_even(x: int) -> bool: return x % 2 == 0 and x > 2 big_even = list(filter(is_big_even, nums)) if __name__ == "__main__": print(odds) print(big_even) 解释与原理 匿名函数降低了“命名成本”，让代码更集中表达意图。 但当逻辑变复杂时，命名函数能提升可读性与可测试性。 常见问题与注意事项 匿名函数是否影响调试？ 是的，栈追踪中缺少函数名。 可以大量使用吗？ 不建议，容易形成嵌套地狱。 与闭包有什么关系？ 匿名函数通常是闭包的常见载体。 最佳实践与建议 简单逻辑用匿名，复杂逻辑用命名 把匿名函数限制在一行或几行内 避免在热路径里频繁创建匿名函数 小结 / 结论 匿名函数是提高局部表达力的工具，但要用在“短小精悍”的场景。 当逻辑复杂时，命名函数更安全。 ...

副标题 / 摘要 好代码不是“聪明”，而是“可理解、可验证、可演进”。本文给出工程视角的判断标准与实践方法。 目标读者 想提升代码质量的工程师 负责代码评审的团队 需要建立编码规范的技术负责人 背景 / 动机 代码质量决定维护成本与交付速度。 在多人协作中，好代码比“聪明代码”更重要。 核心概念 可读性：降低理解成本 可测试性：能被自动验证 可演进性：便于修改与扩展 实践指南 / 步骤 写清晰命名与结构 保持函数短小、职责单一 用测试锁定核心逻辑 减少隐式依赖与副作用 可运行示例 # 不好：命名与职责不清晰 def f(x): if x > 0: return x * 1.08 return x # 更好：意图清晰 def apply_tax(price): if price <= 0: return price return price * 1.08 if __name__ == "__main__": print(apply_tax(100)) 解释与原理 好代码的价值不在于“技巧”，而在于团队可以快速理解与修改。 可读性、可测试性与可演进性是关键指标。 常见问题与注意事项 短代码一定更好吗？ 不一定，重要的是表达清晰。 注释能替代可读性吗？ 不能，注释应补充而不是替代。 可测试性为什么重要？ 它是安全改动的基础。 最佳实践与建议 代码评审关注意图表达 建立清晰的命名规范 把复杂逻辑拆成小函数 小结 / 结论 好代码让团队更快、更稳地交付。 可读、可测、可演进是长期价值的核心。 ...