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

开发需求

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

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

js 复制代码
/**
 * @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、数组形式的注释代码示例

js 复制代码
// 对象形式的注释示例参考上方

/**
 * 模糊搜索选项数组。
 * @type {Array<FuzzySearchOptions>}
 * @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、函数形式的注释代码示例

js 复制代码
/**
 * 异步解封用户。
 *
 * @param {object} data - 包含解封信息的对象。
 * @param {string} data.ban_info.user_id - 被封禁用户的 ID。
 * @param {string} data.game_info.nick_name - 被封禁用户的昵称。
 * @returns {Promise<void>} - 解封操作的 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:&#8203;``【oaicite:1】``&#8203;昵称&#8203;``【oaicite:0】``&#8203;?`, '解封提示', {
      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、组件参数形式注释代码示例

js 复制代码
/**
 * @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<YourComponentProps>}
 */
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` 以及其他信息,以确保注释符合你的项目和团队的规范。
相关推荐
腾讯TNTWeb前端团队2 小时前
helux v5 发布了,像pinia一样优雅地管理你的react状态吧
前端·javascript·react.js
范文杰5 小时前
AI 时代如何更高效开发前端组件?21st.dev 给了一种答案
前端·ai编程
拉不动的猪6 小时前
刷刷题50(常见的js数据通信与渲染问题)
前端·javascript·面试
拉不动的猪6 小时前
JS多线程Webworks中的几种实战场景演示
前端·javascript·面试
FreeCultureBoy6 小时前
macOS 命令行 原生挂载 webdav 方法
前端
uhakadotcom7 小时前
Astro 框架:快速构建内容驱动型网站的利器
前端·javascript·面试
uhakadotcom7 小时前
了解Nest.js和Next.js:如何选择合适的框架
前端·javascript·面试
uhakadotcom7 小时前
React与Next.js:基础知识及应用场景
前端·面试·github
uhakadotcom7 小时前
Remix 框架:性能与易用性的完美结合
前端·javascript·面试
uhakadotcom7 小时前
Node.js 包管理器:npm vs pnpm
前端·javascript·面试