如何在前端项目中制定代码注释规范

本文是前端代码规范系列文章，将涵盖前端领域各方面规范整理，其他完整文章可前往主页查阅~

开始之前，介绍一下最近很火的开源技术，低代码。

作为一种软件开发技术逐渐进入了人们的视角里，它利用自身独特的优势占领市场一角——让使用者可以通过可视化的方式，以更少的编码，更快速地构建和交付应用软件，极大程度地降低了软件的开发、配置、部署和培训成本。

应用地址： https://www.jnpfsoft.com
开发语言：Java/.net

这是一个基于 Java Boot/.Net Core 构建的简单、跨平台快速开发框架。前后端封装了上千个常用类，方便扩展；采用微服务、前后端分离架构，集成了代码生成器，支持前后端业务代码生成，满足快速开发；框架集成了表单、报表、图表、大屏等各种常用的 Demo 方便直接使用；后端框架支持 Vue2、Vue3，平台即可私有化部署，也支持 K8S 部署。

代码注释是软件开发中的重要组成部分，它帮助开发者理解代码的功能和目的，同时也是代码维护和团队协作的基础。一个清晰的注释规范能够提高代码的可读性和维护性。本文将介绍如何在前端项目中制定代码注释规范。

1. 注释的类型

在前端项目中，我们通常有两种类型的注释：

单行注释：用于简短的描述或解释单个语句。
多行注释：用于描述复杂逻辑或文件、模块的信息。

2. 单行注释

单行注释应该紧跟在代码的上一行或同一行的末尾。注释内容与代码或上一行注释应保持至少一个空格的距离。

// 正确的单行注释
const count = 1; // 初始化计数器

// 错误的单行注释
const count = 1;//初始化计数器

3. 多行注释

多行注释通常用于文件头部，描述整个文件的功能，或者用于复杂逻辑的解释。多行注释应该有一个清晰的开始和结束，内容与星号之间保持一个空格。

/**
 * 正确的多行注释
 * 这是一个用于计算数组总和的函数
 * @param {number[]} numbers - 要计算的数字数组
 * @return {number} 数组的总和
 */
function sum(numbers) {
  // ...
}

/* 错误的多行注释
这是一个用于计算数组总和的函数
@param {number[]} numbers - 要计算的数字数组
@return {number} 数组的总和
*/
function sum(numbers) {
  // ...
}

4. JSDoc注释

JSDoc是一种流行的注释规范，它不仅可以提高代码的可读性，还可以被一些工具用来生成文档。在前端项目中，推荐使用JSDoc来注释函数、类和方法。

/**
 * 计算数组总和
 * @param {number[]} numbers - 要计算的数字数组
 * @returns {number} 数组的总和
 */
function sum(numbers) {
  return numbers.reduce((acc, current) => acc + current, 0);
}

5. 注释的内容

注释应该清晰、简洁、有目的。避免无意义的注释或过度注释。注释应该解释为什么这么做，而不是什么在做。代码本身应该清晰到足以表达它在做什么。

// 正确的注释
// 因为用户可能会输入负数，所以在加法前进行检查
if (number < 0) {
  throw new Error('Number must be positive');
}

// 错误的注释
// 检查数字是否小于0
if (number < 0) {
  throw new Error('Number must be positive');
}

6. 代码修改时更新注释

当代码发生变化时，相关的注释也应该相应地更新。过时的注释会误导其他开发者，降低代码的可读性。

7. 注释模板

对于一些重复性的注释内容，如组件、模块、函数等，可以制定统一的注释模板。

/**
 * 组件名称
 * 
 * 描述这个组件的作用和功能
 * 
 * @prop {PropType} propName - 对prop的描述
 */

8. 工具支持

可以使用一些工具来强制执行注释规范，如ESLint的注释相关规则，或者使用Prettier来自动格式化注释，这块会在后续的系列文章中单独说明。

9. 避免注释整块代码

不应该在代码库中保留被注释掉的代码。这些代码往往是过时的，并且会给其他开发者带来困惑。如果需要保留代码的历史版本，应该使用版本控制系统git来管理。

// 错误：注释掉的代码
// function oldCalculate() {
//   // ...
// }

10. 特殊注释标记

在代码中使用特殊的注释标记（如TODO, FIXME, NOTE）来标识需要特别注意的地方，这些标记可以帮助开发者快速定位到需要进一步工作的部分。

TODO: 表示代码中将来需要添加或完成的功能。通常用于提醒开发者还有功能未实现或需要进一步的工作。
FIXME: 指出代码中存在问题，需要修复。这通常表示代码能够运行，但结果可能不是预期的，或者代码本身可能不稳定。
HACK: 指代码中的临时解决方案或者不够优雅的代码。这通常用于快速修复问题，但长远来看可能需要更好的解决方案。
NOTE: 用于强调代码中的某个特别重要的信息，比如解释某个复杂算法的逻辑或者提醒为什么要以特定方式实现代码。
OPTIMIZE: 提示代码的性能可以进一步优化。这不一定表示代码有问题，但可能存在提高效率的机会。
REVIEW: 表示代码需要额外的审查，以确定是否满足需求或是否存在更好的实现方式。
DEPRECATED: 表明代码已经过时，不应该被使用或将来会被移除。
NOCOMMIT: 这是一个警告，表示代码不应该被提交到版本控制系统中。这常用于开发过程中的临时改动，如调试代码。

// TODO: 增加异常处理
function loadData() {
  // ...
}

// FIXME: 这里的算法实现有问题，以后需要优化
function calculate() {
  // ...
}

// NOTE: 这是一个临时解决方法
function temporaryFunction() {
  // ...
}

使用这些注释标签可以帮助团队成员快速识别代码中的特定部分，但它们也不应该过度使用。过多的TODO或FIXME可能表明代码质量问题，应该定期审查和解决这些标记。

11. 开发工具注释

开发工具基本都有便捷指令支持注释，本文只列举在 VSCode 和 WebStorm 这两个编辑器中对代码注释的便捷方式或插件。

在 VSCode 中添加代码注释：

手动添加：通过快捷键 Ctrl + /（Windows/Linux）或 Cmd + /（Mac）添加行注释，在选中代码后按下快捷键即可。也可以手动编写注释。
插件：VSCode 有很多代码注释相关的插件，如 Document This、jsdoc-comment、better-comments、vscode-todo-highlight 等，可以通过 VSCode 的扩展市场安装并使用，提供更丰富的注释功能。