这是一套与编程语言无关、带有强烈主张的准则,目标是写出可维护、可测试、生产级耐用的函数与抽象。资料主张函数首先是抽象实现细节、服务人类读者的沟通工具,代码复用是次要效果,因此不应仅因出现次数多就提取函数;本地推理、可测试性与抽象才是提取的主要动机。
资料定义了“诚实函数”:仅凭签名(入参、出参、返回值)就能完整传达应用自有的依赖、非确定性外部输入与副作用,调用方显式注入本会被隐藏的有状态或可配置外部资源。相反,“不诚实函数”会访问应用自有或有状态的外部资源(数据库、文件系统、网络、全局随机数等),或获取未完全由签名传达的非确定输入,从而妨碍本地推理。语言/运行时自带的原语(如 crypto、Web Crypto、TextEncoder、TextDecoder、atob、btoa 等标准库)可直接使用,不应仅为注入而创建工厂或依赖袋;但可变、可配置、受策略控制的全局状态仍属外部。
诚实函数的分类包括:真正的纯函数、访问器纯函数、可变器(如 clear、remove_if)。不诚实函数包括:不诚实访问器(签名暗示无入参却有隐式全局状态依赖)、副作用器(如 draw_to_screen)、框架钩子(如 C 的 main、Next.js 的 page.tsx、SvelteKit 的 load 与 actions、Arduino 的 setup 与 loop)。
建议:用诚实函数搭建系统,在最顶层注入应用自有或有状态的外部资源;把诚实工作与不诚实编排隔离;将不诚实上提到最高层。签名的首要读者是人:超过三个参数或存在同类型易混淆参数时考虑命名参数或临时参数对象,否则按上下文级到操作级分层排列位置参数;优先使用灵活的接口/泛型;考虑将不变量前置/后置条件上提到类型系统,用令牌作为完成证明,用包装类型表达已校验值;保持同一抽象层级,遵守“相同缩进规则”。