前端代码规范 - 代码注释

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

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

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 的扩展市场安装并使用，提供更丰富的注释功能。

在 WebStorm 中添加代码注释：

• 自动添加：在函数或方法上方输入 /** 并按下 Enter 键，WebStorm 将会自动生成函数注释的模板，然后你只需填写相应的信息即可。
• 自定义模板：可以在 WebStorm 的设置中自定义注释模板，满足团队的特定需求或遵循特定的注释规范。

无论是在 VSCode 还是 WebStorm 中，都可以通过简单的快捷键操作或安装插件来实现代码注释，使代码更易读、易维护。

总结

良好的注释规范有助于提高代码质量，促进团队协作，加快新成员的项目熟悉速度，不仅能帮助自己和他人快速理解代码，还能提高代码的可维护性。在前端项目中，注释不仅仅是给自己看的，更是给团队中其他成员看的，因此应当保持注释的清晰、准确和及时更新。

通过本文介绍的注释规范，希望能帮助你在前端项目中写出更清晰、更规范的注释。

---

看完本文如果觉得有用，记得点个赞支持，收藏起来说不定哪天就用上啦～

专注前端开发，分享前端相关技术干货，公众号：南城大前端（ID: nanchengfe）