code-review-standards

name	code-review-standards
description	用更严格的架构与可维护性视角审查代码改动。适用于用户要求 code review、PR review、diff review、AI 生成代码审查，或特别关注 helper 代码零散、struct/module 组织、重复造轮子、通用库复用、关键代码中文注释不足等问题时。

代码审查标准

审查目标

先审查真实缺陷，再审查会提高后续维护成本的问题：零散 helper 函数、重复的通用逻辑、未复用已有通用库、所有权边界不清晰、关键契约缺少中文注释。

除非用户明确要求修复代码，否则只做审查，不直接改代码。审查输出默认使用中文；代码标识符、API 名称、领域术语可以保留英文。

上下文读取

在判断改动前：

1. 阅读被改动文件和相邻模块。
2. 搜索是否已有类似的工具函数、共享模块、trait、struct、crate 或平台封装。
3. 查看 AGENTS.md、ARCHITECTURE.md、模块 README.md 以及邻近代码风格。
4. 项目本地约定优先于通用代码风格偏好。

结构审查

当多个小型 free function 实际属于同一个领域概念、生命周期、依赖集合或不变量时，需要指出代码过于零散。优先建议使用 struct + impl、内聚的模块类型，或复用已有本地抽象，让所有权、状态、配置和契约更清晰。

不要机械地要求所有纯函数都改成 struct。无状态、真正局部、逻辑简单、没有隐藏共享不变量或依赖的函数可以保持 free function。

重点检查：

• 多个 helper 反复传递同一组 context、config 或 resource，参数列表持续变长。
• helper 必须按特定顺序调用，但代码没有表达生命周期约束。
• 领域规则散落在多个文件里，没有被一个类型或模块负责。
• 新增全局可变状态或隐式依赖，本应作为字段显式传递。
• 出现 Java 风格的过度抽象、类似继承的层级，或职责不清的 manager 对象。

报告这类问题时，说明缺失的内聚点，并指出更合适的归属概念。例如：这些函数共同维护 staging buffer 生命周期，建议收敛到 StagingUploader，由字段显式持有 device/allocator/queue 依赖。

复用审查

重复代码默认视为设计风险，除非它确实是局部且一次性的逻辑。接受新的 helper 前，先搜索：

• 项目已有工具模块、common crate 或共享库。
• 标准库 API，或项目已经使用的成熟生态 crate。
• 相邻渲染、FFI、资源、数学、配置、错误处理路径中的类似实现。
• 模块 README.md 或架构文档中声明的职责边界。

对 diff 中每个新增 helper/free function、局部工具类型、通用适配/转换/格式化函数，都必须逐个过一遍复用门禁。尤其是路径、字符串编码、错误格式化、FFI 指针适配、资源生命周期、配置解析等通用职责，默认应复用已有边界或归入已有边界，而不是留在第一个业务调用点。

如果新 helper 重新实现了已有行为，或它足够通用、未来调用点很可能继续增加，需要指出重复造轮子的问题。建议把共享逻辑放入已有 common module 或拥有该职责的库边界，而不是因为第一个调用点方便就留在局部文件里。

不要为了单个高度特化的分支强行新增共享抽象；除非已经有明确复用压力、正确性契约，或需要集中维护的边界。若保留局部 helper，必须确认它是高度特化、一次性、不会演变成共享职责；否则列为维护性问题。

注释审查

以下代码需要有解释设计意图或关键契约的注释：

• 所有权、生命周期、同步、线程安全、FFI 假设。
• 渲染管线阶段边界、坐标系假设、shader/resource 契约、RenderGraph 依赖。
• 错误处理分支保护的是外部非法状态或关键不变量。
• 模块级职责、非职责、主要抽象、对外契约、重要不变量、依赖关系。

项目自有解释性注释应使用中文。API 名称、领域术语、代码标识符或引用外部材料时可以使用英文。若项目代码中出现只用英文描述设计意图的注释，且周围约定要求中文，需要指出。

不要要求添加只复述显而易见代码行为的注释。

输出格式

按以下顺序输出：

1. 问题列表：包含严重级别、文件/行号、具体风险和建议方向。
2. 开放问题或假设。
3. 简短总结，放在问题之后。
4. 有必要时补充测试或验证缺口。

问题必须具体。避免只说“代码需要更干净”；要指出边界、可复用工具或缺失契约，让修改方向可执行。

发现重复 helper 或未复用已有能力时，问题描述必须指出已有归属 API/模块，以及建议迁移或收敛的方向。