一个巧合，我把文档写进了代码里-白红宇

一个巧合，我把文档写进了代码里

阅读量：424 次

发布时间：2019-03-06

本文共 3546 字，大约阅读时间需要 11 分钟。

最近公司业务调整后，项目需求增加了大量业务组件和高复用逻辑的开发。随着开发团队成员的写作习惯和思想的差异，出现了诸多问题，其中最为突出的两个问题如下：

由于业务组件和业务逻辑分布在各处，想要了解组件是否具备特定属性或钩子方法，通常需要通过查找源代码或直接向开发者请教。这种方式效率低下，且容易引入知识缺口。

部分组件因产品需求、口头沟通和需求妥协的结果，仅适用于特定场景。其他开发人员在设计图或逻辑相似情况下直接复用，结果常常出现各种适配问题。

针对上述问题，我们开始要求组员在开发业务组件时同时编写相应的开发文档或代码注释。初期效果不错，但随着组件迭代频繁，文档更新跟不上，逐渐又回归到靠问答解决问题的状态，第二个问题也随之复现。

某次在 VS Code 调试代码时，发现通过鼠标悬浮在原生语法（如 document.getElementById）或 React 方法（如 useState）上，会弹出一个提示框，显示相关节点、组件、方法的简要介绍和参数说明。这正是我们想要的效果！

进一步调查发现，这个提示框实际上是代码上方的 JSDoc 注释触发的 VS Code 智能提示功能。JSDoc 是一种简单易用的代码注释规范，只需注释开头使用 /** 即可，其他与多行注释无本质区别。以下是通过 JSDoc 写组件和业务逻辑代码的示例：

/** * 关键词高亮组件 *  * @example 
   
   
   
    
    Hello World
    
   
    *  * @param { string } keyword - 关键词 * @param { string } color - 高亮显示的颜色 */
const LightKeyword: React.FC
   
     = ({ color = '', keyword = '', children = '' }) => {
  const [context, setContext] = useState('')
  useEffect(() => {
    // 当关键词为空时，无需对内容做高亮显示
    if (!keyword) {
      return setContext(children)
    }
    const pattern = new RegExp(keyword, 'gi')
    // 通过正则把关键词过滤出来并增加HTML节点
    const allword = (children as string).replace(pattern, (word) => `
    
    
    ${word}`)
    setContext(allword)
  }, [keyword, color, children])
  return (
    
    
    
    
  )
}
export default LightKeyword

还可以通过业务逻辑代码添加详细注释：

import qs from 'qs'
import { message } from 'antd'
import axios, { AxiosRequestConfig } from 'axios'
interface configInterface {
  /** * 请求地址 */
  url: string;
  /** * 请求方式 */
  method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
  /** * 请求参数 */
  data?: any;
  /** * 其他配置参数 */
  options?: {
    /** * 请求头配置 */
    headers?: any;
    /** * 是否启用错误提醒 */
    errorMessage?: boolean;
    /** * 请求类型，默认为json */
    responseType?: 'json' | 'arraybuffer' | 'blob' | 'document' | 'text' | 'stream';
    /** * 是否携带跨域凭证 */
    withCredentials?: boolean
  }
}
// axios全局配置
const $axios = axios.create({
  baseURL: 'https://demo.com',
  timeout: 60 * 1000
})
const useRequest = async 
   
    (
  requestConfig: configInterface
): Promise
    
      => {
  const requestOptions = requestConfig.options || {}
  const axiosConfig: AxiosRequestConfig = {
    url: requestConfig.url,
    method: requestConfig.method || 'GET',
    headers: requestOptions.headers || {},
    responseType: requestOptions.responseType || 'json',
    withCredentials: requestOptions.withCredentials !== false
  }
  // 请求方式为GET时，对参数进行序列化处理
  if (axiosConfig.method === 'GET') {
    axiosConfig.params = requestConfig.data || {}
    axiosConfig.paramsSerializer = (params) => qs.stringify(params, { arrayFormat: 'brackets' })
  } else {
    axiosConfig.data = requestConfig.data || {}
  }
  try {
    const { data: response } = await $axios(axiosConfig)
    // 后端返回错误码，将错误推入catch句柄执行
    if (response.code !== 0) {
      // 错误提醒
      if (requestOptions.errorMessage !== false) {
        message.error(response.message || '未知错误')
      }
      return Promise.reject(response)
    }
    return Promise.resolve(response)
  } catch (e) {
    // 错误提醒
    if (requestOptions.errorMessage !== false) {
      message.error('请求错误，请稍后重试')
    }
    return Promise.reject(e)
  }
}
export default useRequest

配合 TypeScript，代码中的 JSDoc 注释几乎相当于编写文档，极大提升了可读性和智能提示效果。然而在 Vue 3 开发环境中，发现 JSDoc 智能提示仅支持 JS/TS/TSX 文件，不支持 Vue 文件。为了实现 Vue 文件中的智能提示效果，推荐使用 Vetur 插件，并在项目根目录下创建 vetur 文件夹，新增 tags.json 和 attributes.json 文件，并在 package.json 中引入相应路径：

{
  "name": "demo",
  "version": "0.1.0",
  "vetur": {
    "tags": "./vetur/tags.json",
    "attributes": "./vetur/attributes.json"
  }
}

通过这种方式，可以在 Vue 文件中也获得类似的智能提示效果，既不受 Vue 版本限制，又能在一定程度上突破 JSDoc 的格式限制。

转载地址：http://ymcuz.baihongyu.com/

你可能感兴趣的文章