一、注释的必要性
此处省略八百字。
二、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…
就酱，又水了一桶。
