提高前端代码质量要从优雅的注释抓起之TSDoc

一、注释的必要性

此处省略八百字。

二、AirPower使用注释的示例

类的注释

示例

/**
 * # 用户实体
 */
export class UserEntity{
    
}

效果

属性的注释

示例

export class UserEntity{
  /**
   * # 密码
   */
  password!: string
}

效果

方法的注释

示例

  /**
   * # 😜 睡会再起来干活
   * ---
   * ### 🔞 不要忘了`await`，否则没睡醒就起来干活了 :)
   * @param milliSeconds 毫秒数
   */
  static async sleep(milliSeconds: number): Promise<void> {
    return new Promise((success) => {
      setTimeout(() => {
        success()
      }, milliSeconds)
    })
  }

效果

装饰器的注释

示例

/**
 * # 为属性标记可读名称
 * @param fieldName 属性的可读名称
 */
export function FieldName(fieldName: string): Function {
    
}

效果

装饰器参数的注释

示例

export interface IFormFieldConfig extends IFieldConfig {
  /**
   * # 是否必填(字符串类型)
   * ---
   * 💡 支持传入 ```boolean``` 和 ```string```
   * - 如传入 ```有效字符串``` 则认为需要校验, 内容即是校验失败的报错信息
   * - 如传入 ```true``` 则认为需要校验且自动生成校验失败的报错信息
   */
  requiredString?: boolean | string
}

效果

Hooks结构属性的注释

示例

export interface IUseEditorResult {
  /**
   * # 表单的验证规则
   * ---
   * 💡 你可以绑定到 ```el-form``` 的 ```:rules``` 上
   */
  rules: IValidateRule,

  /**
   * # 表单提交的方法
   * ---
   * 💡 你可以使用 ```beforeSubmit``` 方法来拦截请求的数据
   */
  onSubmit: () => void,
}

效果

Vue组件Props参数注释

示例

<template>
</template>

<script lang="ts" setup="props">
import { ref } from 'vue'

const props = defineProps({
  /**
   * # 分组标题
   */
  title: {
    type: String,
    required: true,
  },

  /**
   * # 分组列数
   * ---
   * ### 💡 配置范围 ```1~3```, 默认为 ```1```
   */
  column: {
    type: Number,
    default: 1,
  },
}
</script>

效果

三、注释的原则

• 除非必要，否则不要注释

大概是说，如果已经是约定俗成的、大部分人的共识、一些行业标准等，或者注释本身属于废话，则属于不必要的注释，不需要写注释，也尽可能不要写注释。比如：

<!-- 下面是个div -->
<div></div>

// 声明了一个变量
let money = 100

// 调用alert弹出提示
alert(money)

• 如果必要，注释必须详细

如果需要写注释，那一定是详细的。

自定义的方法，需要将方法大概的功能、需要的参数和类型、方法的返回值、可能抛出的异常(如有)、参考的文档(如有)、弃用的原因(如将弃用)等信息描述完整
条件的说明，需要将条件分支进行说明。
剩下的欢迎评论区补充。

以上是我们在开发过程中的一些注释规范和心得分享，如果你有一些心得，欢迎在评论区分享。

四、参考项目

可以参考我们的前端开源项目的注释示例： github.com/HammCn/AirP...

如果你是 Java 仔，也可以参考我们关于 JavaDoc 的一些注释示例：github.com/HammCn/AirP...

就酱，又水了一桶。