JS函数注释规范及IDE配置

2023-09-14 12:01:53

注释：程序员理解、维护和修改代码的指南

在软件开发中，注释是不可或缺的一部分。它们是程序员添加的书面说明，旨在帮助理解程序，以便于维护和修改。注释的重点在于最大限度地帮助开发者理解代码，尤其是在代码复杂度较高的场景下。其中，函数注释是函数的说明文档，对于清晰地定义函数的作用和行为至关重要。

注释规范

注释最基本的规范是格式规范。一目了然地识别注释的内容，从而确定函数的作用，非常重要。

1.1 函数作用或功能

函数注释的主要作用是函数的作用和功能。在函数的作用或功能时，应避免描述函数的实现，而应直接描述函数做了什么，返回了什么。

格式为：@description descriptionStatements。

例如：

/**
 * @description 计算两数之和
 * @param {number} num1 第一个数字
 * @param {number} num2 第二个数字
 * @returns {number} 两数之和
 */
const sum = (num1, num2) => {
  return num1 + num2;
};

1.2 描述参数

函数注释的另一个主要作用是描述函数的参数。

格式为：@param name description。

例如：

/**
 * @param {string} name 名称
 * @param {number} age 年龄
 * @returns {string} 带有名称和年龄的字符串
 */
const greet = (name, age) => {
  return `Hello, ${name}! You are ${age} years old.`;
};

1.3 描述返回值

函数的返回值是函数执行后的结果。描述函数的返回值时，应尽量详细地描述返回值的类型、内容和范围。

格式为：@returns {type} description。

例如：

/**
 * @returns {Array<string>} 字符串数组
 */
const getNames = () => {
  return ['John', 'Jane', 'Bob'];
};

IDE 配置

不同的 IDE 提供不同的方式来启用函数注释。

2.1 VSCode 配置

在 VSCode 中，通过在 settings.json 中添加以下配置来启用函数注释：

"typescript.preferences.quotePreference": "single",
"javascript.preferences.quotePreference": "single",
"typescript.javascript.implicitProjectConfig.checkJs": true,
"typescript.javascript.implicitProjectConfig.experimentalDecorators": true,
"typescript.javascript.implicitProjectConfig.strict": true,
"typescript.javascript.implicitProjectConfig.module": "esnext",
"javascript.preferences.importModuleSpecifier": "non-relative",