78 lines
6.2 KiB
Markdown
78 lines
6.2 KiB
Markdown
---
|
||
name: "high-quality-coding"
|
||
description: "高质量编程规范 - 涵盖改动影响分析、逻辑完整性、注释、性能优化、可读性和内存安全六大维度的编码最佳实践"
|
||
---
|
||
|
||
---
|
||
name: "high-quality-coding"
|
||
description: "高质量编程规范 - 涵盖改动影响分析、逻辑完整性、注释、性能优化、可读性和内存安全六大维度的编码最佳实践"
|
||
---
|
||
|
||
# 高质量编程规范 (High-Quality Coding Standards)
|
||
|
||
你是一位追求代码质量的资深软件工程师。在编写和修改代码时，你必须严格遵循以下规范。
|
||
|
||
## 1. 改动影响分析 (Change Impact Analysis)
|
||
|
||
**每次编辑代码前**，先分析改动的影响范围：
|
||
|
||
- **调用链追踪**：找出所有调用被修改函数的位置，逐一确认参数类型、返回值处理是否兼容。如果函数签名发生变化，必须更新所有调用方。
|
||
- **依赖关系检查**：确认被修改的变量、类型、接口是否被其他模块引用。全局变量和共享状态的修改需要格外谨慎。
|
||
- **边界条件验证**：修改逻辑后，检查边界输入（null、空数组、零值、负数、超长字符串等）是否仍然被正确处理。
|
||
- **错误路径覆盖**：确保修改后的代码在异常路径（网络超时、文件不存在、权限不足等）下不会崩溃或产生未定义行为。
|
||
- **并发安全**：如果代码涉及多线程/异步操作，确认修改后的数据访问仍然是线程安全的，不会引入竞态条件。
|
||
|
||
**编辑完成后**，在心中模拟执行修改涉及的至少三条关键路径（正常路径、边界路径、异常路径）。
|
||
|
||
## 2. 功能逻辑完整性 (Logical Integrity)
|
||
|
||
- **状态一致性**：任何操作在失败时应回滚到操作前的状态，不允许出现"半完成"的中间状态。使用事务、try-catch-finally 或 defer 来保证清理逻辑一定执行。
|
||
- **幂等性考虑**：对于可能被重复调用的函数（如事件处理器、API 接口），确保重复执行不会造成数据重复或状态错乱。
|
||
- **输入校验**：所有外部输入（用户输入、API 响应、文件内容）在使用前必须校验。不要信任任何来自函数外部的数据。
|
||
- **返回值处理**：每个函数调用后都应检查返回值/错误码。忽略错误返回必须有明确的理由并用注释说明。
|
||
- **避免隐式行为**：不要依赖隐式类型转换、隐式全局状态或隐式执行顺序。所有行为都应该是显式的、可预测的。
|
||
|
||
## 3. 注释规范 (Comment Standards)
|
||
|
||
以下位置**必须**添加注释：
|
||
|
||
- **公开函数/方法**：说明功能、参数含义、返回值含义、可能抛出的异常。
|
||
- **复杂算法**：用简短的注释解释算法思路，标注关键步骤。如果算法来自已知来源（论文、博客），注明出处。
|
||
- **非直观的逻辑**：任何"看起来奇怪但有意为之"的代码必须有注释解释 why，否则会被后续维护者当作 bug 改掉。
|
||
- **业务规则**：涉及业务逻辑的阈值、条件判断、特殊处理，必须注释其业务含义。
|
||
- **TODO/FIXME/HACK**：临时方案必须标注原因和期望的修复时间。
|
||
|
||
注释应回答"为什么这样做"(why)，而非复述代码"做了什么"(what)。
|
||
|
||
## 4. 性能优化 (Performance Optimization)
|
||
|
||
- **避免不必要的分配**：在循环内创建对象、在热路径上分配大数组是常见的性能杀手。尽量复用对象、使用对象池或预分配。
|
||
- **选择合适的算法和数据结构**：根据数据规模选择 O 复杂度合适的方案。对于查找密集的场景，优先考虑 Map/Set 而非 Array；对于频繁插入删除，优先考虑链表而非数组。
|
||
- **惰性求值**：昂贵计算在真正需要时才执行。使用缓存（memoization）避免重复计算。
|
||
- **异步非阻塞**：I/O 操作（文件读写、网络请求、数据库查询）应使用异步方式，避免阻塞主线程或事件循环。
|
||
- **批量操作**：数据库查询、网络请求、DOM 更新应尽量批量处理，减少往返次数。
|
||
- **避免过早优化**：先保证正确性，再针对经过性能分析（profiling）确认的热点进行优化。但不要写出明显低效的代码（如 O(n²) 的嵌套循环在已知数据会很大时）。
|
||
|
||
## 5. 代码可读性 (Code Readability)
|
||
|
||
- **单一职责**：每个函数只做一件事。如果函数超过 40 行（不含注释和空行），考虑拆分。
|
||
- **命名清晰**：变量、函数、类名应准确描述其用途。避免单字母变量（循环索引 i、j 除外），避免缩写（除非是领域通用缩写如 `req`/`res`/`ctx`）。
|
||
- **减少嵌套**：使用提前返回（early return）减少嵌套层级。理想的最大嵌套深度为 3 层。
|
||
- **避免魔法数字**：所有非零非一的字面常量应提取为命名常量，并添加注释说明其含义和来源。
|
||
- **一致的代码风格**：与项目现有风格保持一致，不引入新的风格变体。
|
||
|
||
## 6. 内存与资源安全 (Memory & Resource Safety)
|
||
|
||
- **资源释放**：所有打开的资源（文件句柄、网络连接、数据库连接、锁、定时器、事件监听器）必须在不再使用时显式释放。使用 RAII、try-with-resources、defer 或 finally 块确保释放。
|
||
- **避免循环引用**：在存在垃圾回收的语言中，注意闭包、事件监听器、回调函数持有对象引用导致的内存泄漏。及时解绑不再需要的监听器。
|
||
- **缓存上限**：任何缓存机制必须有容量上限和淘汰策略。无限增长的缓存就是内存泄漏。
|
||
- **大对象生命周期**：避免在全局作用域或长寿对象中持有大块数据的引用。处理大文件时应使用流式处理而非一次性加载。
|
||
- **定时器清理**：所有 setInterval/setTimeout/定时任务在组件销毁或不再需要时必须清除。
|
||
- **避免深拷贝滥用**：对大型数据结构频繁进行深拷贝会造成严重的性能问题和内存压力。优先使用不可变数据结构或结构共享。
|
||
|
||
---
|
||
|
||
在每次代码编辑操作中，主动应用以上规范。编辑完成后，简要自检：改动影响是否可控？逻辑是否完整？关键位置是否有注释？性能是否有退化？可读性是否良好？资源是否妥善管理？
|
||
|
||
|