一个合格的高级开发，首先应该写的一手好注释。

开发需求

1. 着手写代码之前，首先需要充分理解需求，避免无效开发，浪费精力与时间。
2. 遵循单一原则，避免一个函数一两千行代码情况。
3. 抽象化代码，将多组件，多页面使用的变量函数等等都应该抽象出来统一管理。

1、对象形式的代码注释示例

/**
 * @typedef {object} FuzzySearchOptions
 * @property {number} COMBO3 - Fuzzy search by 3-hit combo.
 * @property {number} COMBO6 - Fuzzy search by 6-hit combo.
 * @property {number} COMBO9 - Fuzzy search by 9-hit combo.
 * @property {number} COMBO12 - Fuzzy search by 12-hit combo.
 * @property {number} ELIMINATE6 - Fuzzy search by eliminating 6 targets.
 * @property {number} ELIMINATE10 - Fuzzy search by eliminating 10 targets.
 * @property {number} ELIMINATE15 - Fuzzy search by eliminating 15 targets.
 * @property {number} TOTAL_DAMAGE - Fuzzy search by total damage.
 * @property {number} SINGLE_HIGHEST_DAMAGE - Fuzzy search by single highest damage.
 * @property {number} TOTAL_CLEAR_STEPS - Fuzzy search by total clear steps.
 * @property {number} ENERGY_CONSUMPTION - Fuzzy search by energy consumption.
 * @property {number} TOTAL_CHARACTER_DAMAGE - Fuzzy search by total character damage.
 * @property {number} SINGLE_HIGHEST_CHARACTER_DAMAGE - Fuzzy search by single highest character damage.
 * @property {number} TOTAL_ABNORMAL_VALUE - Fuzzy search by total abnormal value.
 */

/**
 * @type {FuzzySearchOptions}
 * @readonly
 * @description Enum representing fuzzy search options for a game.
 * @author Your Name
 * @version 1.0.0
 */
const FUZZY_SEARCH = {
  COMBO3: 1,
  COMBO6: 2,
  COMBO9: 3,
  COMBO12: 4,
  ELIMINATE6: 5,
  ELIMINATE10: 6,
  ELIMINATE15: 7,
  TOTAL_DAMAGE: 8,
  SINGLE_HIGHEST_DAMAGE: 9,
  TOTAL_CLEAR_STEPS: 10,
  ENERGY_CONSUMPTION: 11,
  TOTAL_CHARACTER_DAMAGE: 12,
  SINGLE_HIGHEST_CHARACTER_DAMAGE: 13,
  TOTAL_ABNORMAL_VALUE: 14,
};


//在这个示例中，`@typedef`定义了一个别名`FuzzySearchOptions`，并通过`@type {FuzzySearchOptions}`为`FUZZY_SEARCH`添加了相应的类型提示。在`@description`中添加了用于描述的信息，以及`@author`和`@version`标签来提供作者和版本信息。你只需要替换`Your Name`和版本号为实际的作者和版本信息即可。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

2、数组形式的注释代码示例

// 对象形式的注释示例参考上方

/**
 * 模糊搜索选项数组。
 * @type {Array}
 * @readonly
 * @description 包含了一组模糊搜索选项，每个选项都有一个显示标签和对应的值。
 * @version 1.0.0
 * @since 2023-11-10
 * @author Your Name
 */
const FUZZY_SEARCH_OPTION = [
  { label: "combo3", value: FUZZY_SEARCH.COMBO3 },
  { label: "combo6", value: FUZZY_SEARCH.COMBO6 },
  { label: "combo9", value: FUZZY_SEARCH.COMBO9 },
  { label: "combo12", value: FUZZY_SEARCH.COMBO12 },
  { label: "消除6个", value: FUZZY_SEARCH.ELIMINATE6 },
  { label: "消除10个", value: FUZZY_SEARCH.ELIMINATE10 },
  { label: "消除15个", value: FUZZY_SEARCH.ELIMINATE15 },
  { label: "卡牌总伤害", value: FUZZY_SEARCH.TOTAL_DAMAGE },
  { label: "卡牌单次最高伤害", value: FUZZY_SEARCH.SINGLE_HIGHEST_DAMAGE },
  { label: "总清除步数", value: FUZZY_SEARCH.TOTAL_CLEAR_STEPS },
  { label: "能量消耗", value: FUZZY_SEARCH.ENERGY_CONSUMPTION },
  { label: "角色总伤害", value: FUZZY_SEARCH.TOTAL_CHARACTER_DAMAGE },
  { label: "角色单次最高伤害", value: FUZZY_SEARCH.SINGLE_HIGHEST_CHARACTER_DAMAGE },
  { label: "异常总值", value: FUZZY_SEARCH.TOTAL_ABNORMAL_VALUE },
];

//替换 `@autho`、`@version` 和 `@since` 中的信息以及其他信息，以确保注释符合你的项目和团队的规范。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

3、函数形式的注释代码示例

/**
 * 异步解封用户。
 *
 * @param {object} data - 包含解封信息的对象。
 * @param {string} data.ban_info.user_id - 被封禁用户的 ID。
 * @param {string} data.game_info.nick_name - 被封禁用户的昵称。
 * @returns {Promise} - 解封操作的 Promise，成功时不返回具体结果。
 * @throws {Error} 如果解封操作失败，将抛出异常。
 * 
 * @description
 * 异步解封用户的过程包括以下步骤：
 * 1. 清除表格的选中项。
 * 2. 重置解封表单中的用户列表。
 * 3. 将要解封的用户 ID 添加到解封表单中。
 * 4. 弹出确认对话框，确认是否解封用户。
 * 5. 调用解封接口执行解封操作。
 * 6. 弹出操作成功提示。
 * 7. 刷新列表。
 * 8. 重置解封表单的用户列表。
 * 
 * @throws {Error} 如果解封操作失败，将抛出异常，并在控制台输出错误信息。
 * @async
 * @memberof YourClass
 * @method
 * @public
 * @version 1.0.0
 * @since 2023-11-10
 * @author Your Name
 */
async onDeblocking(data) {
  try {
    this.$refs.table.clearSelection();
    this.deblockingForm.user_ids = [];
    this.deblockingForm.user_ids.push(data.ban_info.user_id);
    
    await this.$confirm(`是否解封用户 ID：​``【oaicite:1】``​昵称​``【oaicite:0】``​？`, '解封提示', {
      confirmButtonText: '确定',
      cancelButtonText: '取消',
      type: 'warning'
    });

    await userBanned(this.deblockingForm);

    this.$message.success('操作成功');
    this.getList();
    this.deblockingForm.user_ids = [];
  } catch (error) {
    console.error(error);
    throw new Error('解封操作失败：' + error.message);
  }
}

// 根据实际情况填写 `@author`，`@version` 以及其他信息。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

4、组件参数形式注释代码示例

/**
 * @typedef {object} YourComponentProps
 * @property {boolean} isAdd - 是否是添加操作，默认为 true。
 * @property {Object} item - 传入的项目对象，默认为 undefined。
 * @property {number|undefined} allowMatchPattern - 允许的比赛类型，默认为 undefined。
 * @property {boolean} isShowMatchTime - 是否展示赛事时间，默认为 false。
 */

/**
 * 你的 Vue 组件
 * @type {import('vue').ComponentOptions}
 */
const YourComponent = {
  props: /** @type {YourComponentProps} */({
    isAdd: {
      type: Boolean,
      default: true,
    },
    item: {
      type: Object,
      default: undefined,
    },
    allowMatchPattern: {
      type: Number,
      default: undefined,
    },
    isShowMatchTime: {
      type: Boolean,
      default: false
    }
  }),
  // ...其他组件选项
};

/**
 * 作者：Your Name
 * 版本：1.0.0
 * 创建时间：2023-11-10
 */


//在这个示例中，`YourComponentProps` 是一个别名，用于描述整个props的结构。在props的定义上方添加了相应的注释，包括每个属性的类型和默认值。请替换 `Your Name`、`1.0.0` 和 `2023-11-10` 以及其他信息，以确保注释符合你的项目和团队的规范。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42