SuperAPI AI 工具集

self-documenting-code

办公与效率

查看项目

更新于 10-15 23:41

技能介绍

用途:这是一份编写自文档化代码的指南,核心观点是代码应当自我说明,逻辑如何拆分为函数、数据如何组织,决定代码库能否长期维护。

主要能力:

  1. 语义函数:作为代码库的基本构建块,应尽量精简,接收完成目标所需的全部输入并直接返回必要输出,可包裹其他语义函数来描述流程。除非副作用本身就是目标,否则应避免副作用,使其可安全复用。语义函数应无需注释,且易于单元测试。
  2. 务实函数:用于包裹一系列语义函数与特定逻辑,代表代码库中的复杂流程,通常不应在过多地方使用。测试属于集成测试范畴,其内部与行为预期会随时间完全改变,因此适合在上方写文档注释,但应避免复述函数名或显而易见的信息,而记录意外行为。
  3. 模型:数据形状应让错误状态无法表示。每个可选字段都是代码库每次处理该数据时必须回答的问题,松散类型会邀请调用方传入看似正确实则错误的值。模型名称应足够精确,使每个字段是否属于它一目了然。两个常一起使用但相互独立的概念应组合而非合并。形状相同但代表不同领域概念的值,可用品牌类型包装原始类型加以区分。

常见退化:语义函数为图方便变成务实函数,导致依赖它的其他位置做出非预期行为;模型则更缓慢地退化,不断添加可选字段,最终变成半相关数据的松散集合。当模型字段不再围绕其名称保持一致时,就是拆分信号。

限制:资料未提供具体安装命令、平台支持、收费方式或使用步骤。