代码规范与代码审查从个人习惯到团队协作建立可落地的代码规范体系与高效的代码审查流程学习目标读完本文你将学会制定适合团队的代码规范命名、注释、文件组织掌握代码审查的最佳实践和检查清单使用 Git Hooks 自动化规范检查理解 Commit Message 规范与版本管理一、代码规范体系1.1 命名规范// ✅ 清晰、一致的命名// 常量: SCREAMING_SNAKE_CASEconstMAX_RETRY_COUNT3;constAPI_BASE_URLhttps://api.example.com;// 变量/函数: camelCaseletuserCount0;functionfetchUserData(userId){}// 类/构造函数: PascalCaseclassUserManager{}classHttpRequestErrorextendsError{}// 私有属性: 下划线前缀 或 #privateFieldclassBankAccount{#balance0;// 真正私有推荐_internalCache{};// 约定私有}// 布尔值: 使用 is/has/should/can 前缀constisLoadingtrue;consthasPermissionfalse;constshouldRetrytrue;// 文件命名// components/UserProfile.jsx// utils/dateHelpers.js// constants/apiEndpoints.js1.2 注释规范/** * 计算订单总金额含税费和运费 * param {Object} order - 订单对象 * param {number} order.subtotal - 小计金额 * param {number} order.taxRate - 税率如 0.08 * param {number} order.shipping - 运费 * returns {number} 总金额保留两位小数 * throws {Error} 当 subtotal 为负数时抛出 * example * calculateTotal({ subtotal: 100, taxRate: 0.08, shipping: 10 }) * // 118.00 */functioncalculateTotal(order){if(order.subtotal0){thrownewError(subtotal cannot be negative);}consttaxorder.subtotal*order.taxRate;returnNumber((order.subtotaltaxorder.shipping).toFixed(2));}// 行内注释解释为什么而非做什么// ❌ 错误重复代码显而易见的含义letcount0;// 初始化计数器为 0// ✅ 正确解释业务原因letcount0;// 从 0 开始API 要求分页参数从 0 起算1.3 文件组织规范src/ ├── assets/ # 静态资源图片、字体 │ ├── images/ │ └── fonts/ ├── components/ # 通用组件 │ ├── Button/ │ │ ├── index.jsx │ │ ├── Button.test.jsx │ │ └── Button.module.css │ └── Input/ ├── pages/ # 页面级组件 │ ├── Home/ │ └── About/ ├── hooks/ # 自定义 Hooks ├── utils/ # 工具函数 │ ├── date.js │ ├── validate.js │ └── request.js ├── constants/ # 常量 │ ├── api.js │ └── config.js ├── services/ # API 服务层 └── styles/ # 全局样式 ├── variables.css └── global.css二、代码审查Code Review2.1 审查清单## 代码审查检查清单 ### 功能正确性 - [ ] 代码是否实现了需求 - [ ] 边界条件是否处理 - [ ] 错误处理是否完善 ### 代码质量 - [ ] 命名是否清晰、一致 - [ ] 函数是否过长50 行需拆分 - [ ] 是否避免了重复代码 - [ ] 是否有不必要的复杂度 ### 安全性 - [ ] 是否有 SQL/XSS 注入风险 - [ ] 敏感数据是否安全处理 - [ ] 权限检查是否到位 ### 性能 - [ ] 是否有明显的性能问题 - [ ] 循环中是否有不必要的操作 - [ ] 大数据量处理是否合理 ### 测试 - [ ] 是否有对应的单元测试 - [ ] 测试是否覆盖主要路径 - [ ] 测试用例名称是否清晰2.2 审查原则1. 对事不对人 ❌ 你这里写错了 ✅ 这个变量名可能会让人误解建议改为... 2. 解释为什么 ❌ 不要这样写 ✅ 这里如果用户传入 null 会抛异常建议添加默认值 3. 区分严重级别 Blocker: 必须修复安全问题、功能错误 Warning: 建议修复代码异味、性能问题 Nitpick: 可选修复格式、命名偏好 4. 及时响应 - 提交者应在 24h 内响应评论 - 审查者应在收到修改后尽快再次审查三、Git 工作流与提交规范3.1 Commit Message 规范Conventional Commitstype(scope): subject body footer类型说明类型含义示例feat新功能feat(user): 添加用户登录功能fix修复 bugfix(api): 修复空指针异常docs文档更新docs(readme): 更新安装说明style代码格式style: 修复缩进refactor重构refactor(utils): 提取公共函数test测试相关test(user): 添加登录单元测试chore构建/工具chore(deps): 升级 lodash# 示例feat(auth): 支持 OAuth2.0 登录 - 集成 Google 和 GitHub 登录 - 添加 token 刷新机制 - 更新登录页面 UI Closes#1233.2 Git Hooks 自动化# 安装 husky 和 lint-stagednpminstall--save-dev husky lint-staged# 初始化 huskynpx husky init// package.json{lint-staged:{*.{js,jsx,ts,tsx}:[eslint --fix,prettier --write],*.{css,scss,json,md}:[prettier --write]}}# .husky/pre-commitnpx lint-staged# .husky/commit-msgnpx--no-- commitlint--edit${1}// commitlint.config.jsmodule.exports{extends:[commitlint/config-conventional],rules:{type-enum:[2,always,[feat,fix,docs,style,refactor,test,chore]],subject-full-stop:[0,never],subject-case:[0,never]}};四、代码度量与质量控制4.1 复杂度指标// 圈复杂度示例functiongetGrade(score){// 圈复杂度: 5if(score90)returnA;if(score80)returnB;if(score70)returnC;if(score60)returnD;returnF;}// 使用查找表降低复杂度圈复杂度: 1constGRADE_MAP[{min:90,grade:A},{min:80,grade:B},{min:70,grade:C},{min:60,grade:D}];functiongetGrade(score){constentryGRADE_MAP.find(gscoreg.min);returnentry?entry.grade:F;}4.2 SonarQube 质量门禁# sonar-project.propertiessonar.projectKeymy-project sonar.sourcessrc sonar.testssrc/__tests__ sonar.javascript.lcov.reportPathscoverage/lcov.info# 质量门禁sonar.qualitygate.waittrue二、常见误区与注意点误区正确做法代码审查是找茬审查是团队协作共同提升代码质量规范越多越好规则要可执行、可遵守适度即可一次审查提所有问题区分优先级Blocker 必须修Nitpick 可协商Commit Message 随便写规范的提交信息便于生成 CHANGELOG 和回滚只在提交前检查配置 IDE 实时提示问题尽早发现三、动手练习练习 1审查一段问题代码给出一组包含命名不规范、缺少错误处理、重复代码的示例按检查清单逐项审查。练习 2配置完整的前端工程规范配置 ESLint Prettier Husky Commitlint 的完整工作流。四、AI 辅助学习4.1 本节知识点的 AI 提问模板“如何制定适合小团队的代码规范”“代码审查时如何给出有建设性的反馈”“Commit Message 规范的完整规则是什么”4.2 警惕 AI 的常见错误AI 可能推荐过于严格的规则集需根据团队规模调整AI 可能混淆不同的 Git 工作流Git Flow vs GitHub Flow五、配套代码本文示例代码位于CODE-ADVANCED/15-代码规范与代码审查/文件名说明code-review-checklist.md代码审查检查清单模板commitlint-demo.jsCommit Message 规范验证示例husky-setup.shHusky lint-staged 配置脚本六、本章小结代码规范包括命名、注释、文件组织三个层面代码审查应以协作态度进行区分问题优先级Conventional Commits 规范便于自动化版本管理和 CHANGELOG 生成Git Hooks 实现提交前自动化检查防止问题代码入库如果本文对你有帮助欢迎点赞、收藏、关注专栏。有任何问题可以在评论区交流