前端注释规范-建议

注释规范

注释是一个磨刀不误砍柴工的活，只是顺手的事，自己阅读起来会快减少阅读、理解成本，大家都写注释，互相了解起来方便如果真的开发任务很重，可以把握优先级，把核心的注释写好注释写的好，不一定是好程序员，但是注释写的不好，肯定不是好程序员

目的

减少他人维护代码时的探索时间，增加可读性、可维护性。

原则

如无必要，勿增注释 As short as possible
如有必要，尽量详尽 As long as necessary

需要写注释的地方

业务页面、组件的顶部注释

组件中文命名
描述，可选

注意事项，有则必写

<!-- 战役详情列表-流水票据-头部信息组件 -->
<template>
  <div class="business-flow">

工具函数

函数名

所有入参

/**
 * @description: 获取开始结束日期之间的所有日期（包括开始、结束）
 * @param {*} stime 开始日期时间戳
 * @param {*} etime 结束日期时间戳
 * @param {*} toDate 输出结果是否转换为日期（年-月-日）
 * @return {*}
 */
export function getSectionDate(stime, etime, toDate = false) {
  if (!stime || !etime) {
    return [];
  }
  // 初始化日期列表，数组
  var section = [];
  // 开始日期小于等于结束日期,并循环
  while (stime <= etime) {
    section.push(toDate ? dateFns.changeTime(stime, null, true) : stime);
    // 增加一天时间戳后的日期
    stime = stime + (24 * 60 * 60 * 1000);
  }
  return section;
}

复杂模块的逻辑
- 简单注释，描述太多说不清楚
上下游影响比较大的代码
不常见的单词
- 单纯靠名字不能理解意思或用法的方法、变量、常量名
影响较大的全局代码以及修改全局代码、样式等
标注修改用途和影响范围
比较反常的处理
- 例如某业务要求的特殊逻辑

解决特殊问题或兼容问题

专门 fix 某个不常见的 bug，需要添加注释

  // 修复有时候不能正常显示选中项的问题
  setSelected() {
    this.$nextTick(() => {
      const target = this.$target;
      if (target && typeof target.setSelected === 'function') {
        target.setSelected();
      }
    });

所有接口注释文档地址

  // https://yapi.lanhanba.com/project/307/interface/api/50735
  get('/h5/locxx/requirement/selection', { modules: 'tenancy,rentMode' }, { isMock: false }).then((response) => {
    setSelection(Object.assign({}, selection, {
      tenancy: refactorSelection({ selection: contrast(response, 'tenancy', []) }),
      rentMode: refactorSelection({ selection: contrast(response, 'rentMode', []) }),
    }));
  });

所有枚举字段注释枚举值

比如 type 合同类型：1 商家，2 供应商

  // 收款信息添加的目标类型：1 订单供给，2 订单商家
  type: {
    type: Number,
    default: 1,
  },

待优化的点，命名规则为 TODO 姓名首字母
- // TODO zs
临时注释，请勿删除，可能后期会用到
- 一些临时注释掉的代码逻辑，后期开发可能会用到，标注注释防止别人优化代码删掉注释
组件内未调用的属性、函数，父级调用（vue 较常见）
- 防止他人维护时，组件内搜不到后删除

帮助用户理解文件结构（可选）

{/* 合作方式 */}
<Cooperation ref={cooperationRef} options={selection?.rentMode} onComplete={methods.cooperationComplete} />

{/* 理想位置 */}
<IdealPosition ref={idealPositionRef} type={type} onComplete={methods.idealPositionComplete} />

{/* 落地方案 */}
<LandingPlan ref={landingPlanRef} onComplete={methods.landingPlanComplete} />

不建议的注释

业内公用逻辑，比如 vue 生命周期，常用内置方法，浏览器方法等
命名+逻辑简单的方法，例如 getData，getUserInfo......
内容过长时的单行注释，影响阅读体验，建议换行
情绪注释
- 如 今天心情不好这里加个注释
空内容的注释