coding

编码

目标

编写的代码应当有理有据：其结构应由运行方式、处理的数据以及证明其行为仍然正确的证据所支撑。

优先采用直接、可衡量的推理，而非抽象的架构偏好。在两种设计之间做选择时，应考虑它们对运行时、内存流量、分配次数、分支结构、数据局部性、生成代码和验证成本的影响。

默认工作流

1. 阅读本地规则。编辑前检查仓库说明和相关源代码。
2. 找到实际路径。确定请求会修改的代码路径、读取和写入的数据，以及验证行为的边界。
3. 有意识地复用。添加新内容前，搜索已有类型、辅助工具、文件夹和验证命令。
4. 选择最简单且高效的结构。逻辑优先使用函数，状态使用简单的数据对象，输入和输出应明确，并采用能让热点数据保持紧凑的布局。
5. 搭建测量基础设施。对于性能敏感或结构性工作，应创建或使用能测量相关开销的工具。没有测量工具就开展工作，等于盲目行事。
6. 在缺少上下文时添加注释。用浅显的语言说明热点路径、内存布局、测量边界和出人意料的权衡。
7. 验证。运行能够证明改动正确的针对性测试、类型检查、基准测试、跟踪或验证命令。
8. 总结证据。报告行为变更、相关的性能边界、验证命令和遗留风险。

以性能为依据的设计

• 在性能可能重要时，让性能指导代码风格。只有当对象、抽象、文件夹和间接层能带来足以抵偿其成本的运行时、内存流量、局部性、可验证性或可读性改善时，才使用它们。
• 不要把函数长度、文件数量或对象数量等任意规则当作品质证明。拆分代码的前提是能改善数据流、所有权、测量、局部性或验证。
• 添加抽象前，说明它能节省什么：重复工作、复制的字节、分配、分支、分散读取、编译时重复，还是测试复杂度。
• 移除抽象前，说明这样能让什么更经济或更清晰：减少调用、减少状态、简化生成代码、让数据更紧凑，还是缩小验证范围。
• 对性能敏感的代码，在确有必要时检查实际目标：基准测试输出、跟踪输出、分配器计数、内存布局、编译器输出、反汇编或硬件计数器。
• 默认针对计算资源受限的环境进行优化：数据紧凑、内存流量少、循环可预测、尽量减少分配，且不依赖不必要的产品层依赖。

状态与逻辑

• 逻辑优先使用函数，状态优先使用简单的数据对象。
• 对象和类主要用于保存内聚的数据和简单的生命周期规则。避免使用隐藏控制流、分配或性能开销的复杂变更方法。
• 明确管理状态。直接传递存储、工作区、上下文和缓冲区，不要将它们隐藏在全局可变状态之后。
• 对真实的领域概念或数据布局概念使用具名类型。如果原始字符串、字典或整数标志会导致验证和含义分散到各个调用点，就不要使用它们。
• 不要引入新的以下划线开头的变量名。使用能清晰说明值含义的名称；只有在确实忽略某个值时，才使用该语言的丢弃模式。除非外部 API、生成代码或当前修改区域的既有惯例另有要求，否则辅助函数、文件和模块也遵循这一偏好。
• 如果采用大量对象的设计，应检查它是否改善了局部性和清晰度，还是增加了指针跳转、隐藏的变更、分配和测试难度。

文件夹结构

• 如果代码在运行时用途、数据所有权、验证方式或变更节奏上相同，就将它们放在同一个文件夹中。
• 按实际边界拆分文件夹：输入/加载、准备、计算、输出/报告、验证、基准测试和检测。
• 计算代码应与 CLI 解析、文件 I/O、报告组装、兼容性适配器以及分析器/导出逻辑分离。
• 除非产品代码提供精简的检测门面，否则应将基准测试、验证、跟踪和临时工具放在产品代码路径之外。
• 如果多个文件处理相同的数据形状，优先使用小而专注的文件夹，而不是混杂的工具集合。

脚手架与检测

脚手架是临时的或局部于边界的代码，用于帮助理解性能、正确性和数据形状。对于非平凡的实现工作，应尽量构建脚手架。缺乏良好检测就开展工作，无异于盲目行事。

边界很重要：不应让没人要求的永久性脚手架污染成熟的生产代码。在这种情况下，先在临时空间中直接构建基准测试、跟踪、计数器或测试框架：/tmp、被忽略的本地目录或其他可丢弃的位置。它不应被导入、接入常规构建、向用户公开或提交。如果值得保留检测机制，应提供将其编译移除的方法，或将其置于明确选择启用的构建路径之后。将检测机制或保留的基准测试资产移入仓库前，请先征求用户同意。

• 微基准测试用于测量单个函数、循环、解析器路径、分配器模式或布局选择。
• 端到端基准测试用于测量真实用户或生产边界，包括设置和输出工作。
• 跟踪区域和时间线分析用于展示阶段形态、嵌套关系、重叠、停滞以及时间消耗所在。它们用于解释成本，并非未经检测的运行时。
• 低开销计时用于以最低的观测成本测量经过的运行时间。用它来支持前后性能对比的说法。
• 当问题涉及布局或分支行为时，硬件计数器用于测量周期数、指令数、缓存未命中、分支未命中和内存停顿。
• 分配计数器或分配器包装器用于测量分配次数、分配大小、峰值存活字节数、内存周转，以及意外的热循环分配。
• 内存布局报告用于测量结构体大小、填充、跨越的缓存行、保留的堆大小、栈占用和复制的字节数。
• 编译器输出或反汇编检查用于显示编译器是否生成了预期的加载、存储、调用、分支、除法、向量化或内联。
• 黄金输出验证用于证明优化后的代码仍会产生相同的可观察行为。
• 临时测试框架可快速隔离问题，且不必更改成熟的产品代码。除非用户希望保留检测机制，否则应将其保持为可丢弃的临时内容。

检测规则：

• 产品代码可以通过一个小型门面发出精简信号。
• 产品代码不得了解跟踪文件、报告格式、分析器配置、Shell 脚本或仪表板。
• 检测机制不得演变为配置模块、调度器、状态管理器或备用实现路径。
• 应将保留的检测机制编译移除、默认设为空操作，或仅通过明确启用的基准测试/跟踪构建来启用。
• 在成熟代码库中，应优先先在临时空间中进行检测。仅在用户提出要求或同意将其作为长期保留的证据时，才提交检测机制。
• 保留的证据应放在仓库的验证或基准测试区域；临时跟踪和探索输出应保持为可丢弃内容。
• 当发现已转化为代码、测试、注释或保留的证据后，应删除脚手架。

注释

• 仅在注释能保留读者无法单凭代码还原的上下文时添加注释。
• 对热路径、内存布局、埋点边界和不明显的权衡，优先使用简洁、结构化的注释。
• 考虑下一位读者所处的情境。不要假设他们了解性能调查、失败的替代方案或基准测试历史。
• 使用简单的语言。除非代码库已使用某个术语，否则避免使用行话；并将技术术语与具体效果联系起来，例如“加载更少的字节”“避免逐项分配”或“让低频数据留在循环之外”。
• 好的结构化注释通常会回答以下一个或多个问题：Why:、Tradeoff:、Evidence:、Boundary:。
• 不要叙述语法，也不要复述名称。一条有用的注释胜过几条巧妙却含糊的注释。
• 保留用户编写的备注，例如 Feedback:，除非用户明确要求移除。

硬切换规则

• 不要优先实现回退方案。默认采用硬切换。
• 未经用户明确批准，并且未提供负责人、移除日期、跟踪问题和验证计划时，不要使用兼容垫片、双路径、双重读写或旧版回退。
• 不要使用会静默回退到旧行为的宽泛 catch 块。
• 不要对新旧字段名混用 or/|| 链并设置静默默认值。
• 如果要替换旧行为，在安全的情况下，应在同一个完整变更中删除旧路径。

反模式

• 仅凭个人偏好、模式名称或笼统的“整洁代码”说法来论证性能敏感的选择。
• 使用对象隐藏逻辑、变更、分配或慢路径的面向对象设计。
• 通过拆分文件夹，将同一个运行时概念分散到抽象层之间。
• 让埋点渗入产品行为，或发展成第二套架构。
• 对重要的性能或结构工作不做埋点，随后仅凭代码形态猜测。
• 未询问是否应保留，就将脚手架代码提交到成熟代码库中。
• 基准测试比较不同的边界、预热状态、工作线程数或验证条件。
• 通过增加热路径中分散的读取、分支或重复计算来减少内存占用。
• 主要用于转发调用，同时保留旧名称或旧路径的兼容包装器。
• 新增以下划线开头的名称来表示私有、临时或“内部”代码，而不是选择清晰的名称。
• 添加当前没有实测需求的推测性参数、钩子、配置或抽象。
• 在进程边界、FFI 边界或真正的单例之外使用全局可变状态。
• 使用行话掩盖不清晰决策的注释。

审查清单

• 哪条路径发生了变化？行为在哪里得到验证？
• 重要的循环或工作流会读取和写入哪些数据？
• 所选结构是否减少了运行时间、内存流量、分配、分支成本或验证成本？
• 是否避免新增以下划线开头的名称，除非外部接口或生成接口有此要求？
• 如果添加了对象/类，它们是否只是简单的状态容器，而非隐藏逻辑的容器？
• 文件夹结构是否按实际的数据/运行时归属组织代码？
• 是否使用了相关的脚手架或埋点，而不是凭猜测？
• 埋点是否位于产品层之外，或置于单一且精简的门面之后？
• 如果代码库已成熟，是否在提交保留的脚手架代码之前使用了临时埋点？
• 基准测试和验证的边界是否清晰且可比较？
• 注释是否简洁、结构化、通俗易懂，并且对不了解你上下文的读者有用？
• 是否避免了优先采用回退方案的兼容脚手架？
• 是否移除了过时的脚手架、无效路径和推测性钩子？