提示：引入注释工具，统一注释格式

前言

代码注释是程序设计者与程序阅读者之间通信的重要手段。应用注释规范对于软件本身和软件开发人员而言尤为重要。

在团队中引入注释工具，

统一注释格式

，方便快捷编写注释显得更加重要。对于vscode的项目我们推荐使用

koroFileHeader

插件。

koroFileHeader是什么？

用于生成文件头部注释和函数注释的VSCode插件，支持所有主流语言,功能强大，灵活方便，文档齐全，食用简单！

集成步骤

安装

在 Vscode 扩展商店中搜索koroFileHeader, 点击安装。

配置

（1）

查找配置文件setting.json：

vscode工具栏→code→首选项→设置→搜索settings.json→编辑settings.json

（2）

插入配置内容：

在settings.json的后面插入配置内容（统一）

...

  "fileheader.customMade": {
    // 文件头部注释
    "Author": "Json", // 开发者名字
    "Date": "Do not edit",
    "LastEditors": "Json", // 开发者名字
    "LastEditTime": "Do not edit",
    "Description": "",//文件说明描述
    "FilePath": "Do not edit" // 增加此项配置即可
  },
  "fileheader.cursorMode": {
    // 函数头部注释
    "description": "",//函数功能描述
    "param": "params",//函数对应参数
    "return": ""//函数
  },
  "fileheader.configObj": {
    "autoAdd": true, // 默认开启自动添加头部注释，当文件没有设置头部注释时保存会自动添加
    "autoAlready": true, // 只添加插件支持的语言以及用户通过`language`选项自定义的注释
    "prohibitAutoAdd": ["json", "md"], // 黑名单，禁止.json .md文件，自动添加头部注释
    "folderBlacklist": [ "node_modules" ], // 文件夹或文件名禁止自动添加头部注释
    "wideSame": false, // 头部注释等宽设置
    "wideNum": 13 // 头部注释字段长度 默认为13
  }
...

（3）重启编译器便可

使用

常用的注释有三种，文件头部注释，函数注释，函数内的逻辑代码注释

文件头部注释

• 
  快捷键：
  
  
  mac：
  
  
  ctrl+cmd+i
  
  ，
  
  window：
  
  
  ctrl+win+i
  
• 
  注释内容包含：
  
  创建者，创建时间，最后编辑者，最后编辑时间，文件描述，文件路径
• 保存文件的时候，自动更新最后的编辑时间和编辑人
• 
  注释格式示例：
  

/*
 - @Author: Json
 - @Date: 2022-06-16 12:03:56
 - @LastEditors: Json
 - @LastEditTime: 2022-06-17 11:36:26
 - @Description: 首页-我的
 - @FilePath: /sub_rn_sample/app/pages/mine/index.tsx
 */
import BasePageView from '@/c/BasePageView';

函数注释

• 
  快捷键：
  
  
  mac：
  
  
  ctrl+cmd+t
  
  ，
  
  window：
  
  
  ctrl+win+t
  
• 将光标放在函数行或者函数上方的空白行，操作快捷键自动生成
• 自动解析函数参数，生成函数参数注释。
• 
  注释格式示例：
  

/**
 - @description: 跳转到指定页面
 - @param {string} page 要跳转的页面
 - @param {any} params 要传递的参数Json
 - @return {*}
   */
  static goPage(page: string, params: any = {}): any {
  }

函数内的逻辑代码注释

• 直接使用“//”注释，代码示例：

const LoginPage = (_props: any) => {
  //入口设置navigation
  NavigationUtil.init(useNavigation());
  ...
  }

总结

本文仅仅简单介绍了koroFileHeader的使用，以及团队统一注释的配置。

koroFileHeader还提供了大量能使我们快速便捷地注释的功能和配置，包括图像注释以及其他自动化配置项，大家可以直接到官方文档查看和学习。