规范前端注释：JSDoc基础入门

当你封装一个参数很多的函数，有时我们自己都会忘记各个参数的含义，更不用说让团队里的其他人使用了。因此，良好的注释是必不可少的。本篇文章将介绍如何运用jsdoc来规范注释。

示例

以我这篇文档的代码为例：

前端Ajax请求从后端获取二进制文件并下载-CSDN博客

/**
 * 下载二进制文件
 * @param {string} method 必填 请求方式
 * @param {string} url 必填 下载 url
 * @param {object} [data={}] post 请求的 data
 * @param {object} [headers] 请求的 headers
 * @param {string} [filename=下载.zip] 保存的文件名，默认为下载.zip
 * @param {boolean} [isDownload=true] 是否直接下载，默认为 true
 * @param {object} [blobType={}] 指定 blob MIME 类型，默认为{}
 * @returns {string} blobUrl
 */
export async function getBufferFile(
  method,
  url,
  data = {},
  headers,
  filename = '下载.zip',
  isDownload = true,
  blobType = {},
)

然后编写调用这个函数的代码时就能自动看到各项注释，注释的提示效果：

 

详解各部分

注释以/**开头，每行前面一个*，最后是*/结尾。如果你使用的ide是vscode，可以很方便的在函数名上方直接输入/**然后回车，就能自动帮你把各参数列出来：

/**紧接着的下一行，是对函数整体的注释，可以描述功能和使用场景等：

 

@param代表各个入参，后面的{}里是入参的数据类型，*代表any什么类型都可以。支持多个类型，写法是{(string|string[])}，加个小括号并用|分割。

{}后面是参数名，如果是可选参数写法是[data]，加上方括号，有默认值的写法是[data={}]。

文字注释空一格直接写在后面。

另外参数名还支持注释对象类型的各属性：

@returns用来注释函数的返回值，写法和上面基本一致。

这样就介绍完jsdoc最常用的写法了，其他较常用的还有对class，mixin等注释的支持，大家可以自行查阅文档JSDoc 入门 | JSDoc中文文档 | JSDoc中文网

对函数进行注释，将大幅提升代码可读性，也更加友好于团队协作。如果你尚未掌握此技巧，赶快来学习吧！