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

开发需求

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

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`和版本号为实际的作者和版本信息即可。

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` 中的信息以及其他信息，以确保注释符合你的项目和团队的规范。

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` 以及其他信息。

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` 以及其他信息，以确保注释符合你的项目和团队的规范。