VSCode 注解就是你的文件

在使用文字编辑器时,你是否有以下状况呢?

  • 搞不懂,为什麽文字编辑器总是没跳提示
  • 函式库没有安装插件就不知道如何输入
  • 同事或过去自己写的函式不知道在写什麽,都要花上许多时间去理解
  • 想要为函式补充注解,但不知道如何着手

那麽你可以试着使用 VSCode,强大的 Intellisense 搞定所有函式提示!

函式的提示

使用 Sublime Text 或 Atom 时,当载入外部的套件需要加上文字提示时,就需要另外安装相应的套件;而 VSCode 本身的 Intellisense 就有提供强大的提示功能,不安装额外套件的情况下就能提供许多的提示。

以 jQuery 来说,只要外部资源载入的情况下,不需要另外安装其它 jQuery 相关插件就能够获得程序码的提示。

首先,先将 jQuery 载入到网页内(需要完整版的 jQuery 才能有此功能)。

<script src="https://code.jquery.com/jquery-3.5.1.js"></script>

输入 $. 的情况就会列出 jQuery 的所有方法,开发者可以直接使用上下按键进行选择,所有的方法也有提供相对应的说明(如文中是 jQuery 的 get 方法,作用是发出 GET 请求)。
https://ithelp.ithome.com.tw/upload/images/20201013/200836080ArX8J9KVF.png

$() 选取器内,也会提示是需要带入选取器的表达式。
https://ithelp.ithome.com.tw/upload/images/20201013/20083608GIQi3ts6os.png

链接的方法在运用上也是没有问题的,以下选择一个 DOM 元素後,加入 . 也会列出更多相应的方法。
https://ithelp.ithome.com.tw/upload/images/20201013/20083608tbbXNfbnqq.png

自订你的文件

既然 jQuery 的提示不安装套件就能运作,那麽是否自订的函式也有此功能呢?

当然有的,官方文件 中对此也有完整的说明,介绍该如何自订属於自己的提示文件。以下我们就手把手来为函式加入说明文件吧。

以下是 JS 文件的范例,文件的规范可参考,如果直接看范例可能会不知如何着手,而 VSCode 对此其实有很完整的支援,不需要自行建构这些文件格式。

/**
 * 这是相加的功能
 * 
 * @param {Number} a 数值 1
 * @param {Number} b 数值 2
 * @returns {Number} 相加後的数值
 */
function add(a, b) {
  return a + b;
}

首先,需要一段范例程序码,以下是简单的相加函式。

function add(a, b) {
  return a + b;
}

接下来在函式的前方连续输入 /** 就会直接出现文件的样板,文件的样板会自动带入该函式的参数、回传栏位,接下来只要专注在文档撰写即可。
https://ithelp.ithome.com.tw/upload/images/20201013/200836088bJhQLBuFK.png

接下来就可在产生的模板中输入相对应的说明文档:
https://ithelp.ithome.com.tw/upload/images/20201013/200836080OttNyX4nV.png

撰写范例,撰写中 VSCode 也会跳出提示(型别提示),也特别注意此段注解必须相邻於函式才可运作。

/**
 * 这是相加的功能
 * 
 * @param {Number} a 数值 1
 * @param {Number} b 数值 2
 * @returns 相加後的数值
 */
function add(a, b) {
  return a + b;
}

实际演示,在後方程序码输入 add 则会出现 Intellisense 的提示,提示内容就是刚刚所撰写的文档(相信自己写一次以後,也更能看懂函式库的文件说明)。
https://ithelp.ithome.com.tw/upload/images/20201013/20083608nc0rWamr4A.png

add() 括号内也会分别带出两个参数的说明。
https://ithelp.ithome.com.tw/upload/images/20201013/20083608UfVRPycU83.png

add() 第二个参数说明。
https://ithelp.ithome.com.tw/upload/images/20201013/20083608iPuDqtm5I2.png

import/export 的外部资源也能运作

Intellisense 可以直接侦测与本文件中有哪些相依的档案,因此外部汇入的档案依然可运作,以下将程序码改用 export default 的方式进行汇出。

export default {
  /**
   * 这是相加的功能
   *
   * @param {Number} a 数值 1
   * @param {Number} b 数值 2
   * @returns {Number} 相加後的数值
   */
  add(a, b) {
    return a + b;
  },
};

接下来在另一个档案中汇入该档案,图片中可看到 Intellisense 的功能可以正常运作。
https://ithelp.ithome.com.tw/upload/images/20201013/20083608dAEIJIdvMs.png

结语

VSCode Intellisense 的效能优於许多文字编辑器,且不需要安装套件就可直接载入函式库的说明,函式库的方法新增、调整也不用担心,因为文档是随着载入的函式库进行运作。

除此之外在多人协作时,也可透过注解的形式加入特定函式的说明文档,让其他协作的开发者能够轻松上手。


<<:  《Day 28》【软件资料库】SQLServer 镜像建置PART 1

>>:  [28] 30 天从 Swift 学会 Objective-C:Swift friendly 的 API Swift name

菜鸟日记Day 28-如何为时钟刻上数字?

昨天我们以setInterval的方式,将指针放到时钟上并设定间隔,每秒钟执行1次setTime函式...

[Java Day15] 4.3. 参数

教材网址 https://coding104.blogspot.com/2021/06/java.h...

C# 入门之字符串处理

在很多情况下,我们需要通过程序去处理一些文本,文本都是以字符串表示的,所以我们今天来看一看,使用 C...

Day29|常见的三种工作流程 - Git flow、GitHub Flow 与 Gitlab Flow

在制作专案时,大多都是与他人共同协作,当一起开发的人越来越多时,就更需要有一套规则或模式来进行合作,...

IPv6 路由问题

架构图 https://imgur.com/gRWBf3i DIR-818 的路由表 https:/...