持续创作，加速成长！这是我参与「掘金日新计划 · 6 月更文挑战」的第8天，点击查看活动详情
好的代码，注释肯定不能少，就目前而言基于 的项目大部分都是使用的 ， 相对于 的支持没有那么完善，大部分包括我目前工作所在的团队，使用的 版本都是采用 并且不带 支持，对于曾经用过或者习惯使用强类型的，难以离开 编码提示的人来说，这其实很难受，那么目前 项目可以通过 通过加注释的方式去过渡类型，配合 在某些情况能够达到使用 差不多的体验
最新版本更新了 JS 常见注释的写法和小细节
关于 的相关定义可以参考这个链接，讲的挺多，甚至有很多用不上，可以考虑当成一本字典
前端我用过的 时间比较长的只有 和 ，先不去纠结它们的好坏，它们对方法的注释都可以使用 ，如下动图
没有像 那种环境的约束的话，还是很难让人有动力去写注释的，所以一般人写的注释都是写个 啥的，就是类似下面的情况
常用的就是这些，用来写下约束一下表单还是很好用的，还有数组之类的可以加上去尝试一下
二维数组也可以使用
- 可选参数
- 可选参数
例子如下
效果如下
- 参数默认值
例子如下
效果如下
PS: VS Code 对默认值的支持不够，效果如下
当参数为数组时可以做到对其每个元素进行详细描述，格式如下
例子如下
效果如下
对于数组的注释，我个人感觉一般，不能达到 的效果，不建议对数组参数里面的每个索引值进行描述，有可能会引发歧义
暂时没有找到一个很专业的名词来介绍这部分，姑且就用它的使用范围来介绍，对象结构就是，某个参数可能是一个固定的结构的对象，类似于
像这种情况，注释可以这样写
还算不错的提示
用在返回上面也是很方便的
但是 到了这一步，格式化就没有很方便了，并不会对其中的结构体做特定的格式化（包括 ），这也算是很少有人去写这方面注释的一个原因，没有规范的定时炸弹，如果能出一个插件去补全这块，说不定可以激发前端程序员在非 项目写上两句注释的动力
如果你的方法参数是 形式，像上面的写法，会让维护者不解其中的意思，如下
所以可以采用另一种描述 中各项的描述，如下
WebStorm 效果
可以看到注释和类型，非常的不错
VS Code
同样的代码在 上是这样的
并没有对应的属性注释，如果是下面这种写法就可以了
但这样就有点麻烦了，我建议采用在 的写法，在 编码时，就采用跳转的方式查看注释，类似下面这种效果
使用 作为参数，一般用在配置项的场景
- 有些函数的参数并不是作为算法的输入，而是对算法的某些分支条件判断之用，比如 值
- 对于一些硬编码或者枚举值参数可以解释它的具体意思，如上例子
- 方法重载，比如上面那个例子，我既想用 又想用 ， 可能是可选参数，使用配置型参数设计就可以解决
更多关于参数的设计，请参考JavaScript编码规范 - 3.8.2 参数设计
有些时候我们可能需要使用复用一些结构体，可以使用 封装，如下
在这块的注释方面就比不上 了
在复用这方面，就不如 好用了，说实话，如果你的项目都需要用到这种类型了，应该尽快考虑是否应该使用 ， 的生态方面还是比不过 的，而且两者写法差距蛮大，一旦写得多了，调头比较难
接口 的注释还是挺重要的，如果 能用在这上面还是挺方便的，其示例如下
效果还行
偶尔使用 写点简单的注释还行，但是复杂的项目和类型， 和它的生态未必能够撑得住
- JSDoc 中文文档
- 模板使用自定义类型_你不知道的类型检查(JSDoc版)
- JavaScript 编码规范 - 2.4.8 函数/方法注释
- JavaScript编码规范 - 3.8.2 参数设计
版权声明：
本文来源网络，所有图片文章版权属于原作者，如有侵权，联系删除。
本文网址：https://www.mushiming.com/mjsbk/10571.html