代码注释

在 Visual Studio Code (VSCode) 中，代码注释是标准的做法，用以解释代码的功能、目的、复杂之处或者暂时禁用某段代码。以下是如何在不同编程语言中添加代码注释的方法：

单行注释

几乎所有编程语言都支持某种形式的单行注释。以下是一些示例：

HTML:

<!-- 这是单行注释 -->

JavaScript/TypeScript/CSS/SCSS/JSONC:

// 这是单行注释

Python:

# 这是单行注释

C/C++/C#/Java:

// 这是单行注释

多行注释

多行注释通常用于注释掉一大块代码或提供多行的文档说明：
HTML:

<!--
  这是一个多行注释的例子。
  它可以跨越多行。
-->

JavaScript/TypeScript/C/C++/C#/Java:

/*
  这是一个多行注释的例子。
  它可以跨越多行。
*/

Python: Python 没有专门的多行注释语法，但可以使用连续的单行注释或三引号来创建类似效果。

'''
这是一个多行注释的例子。
它可以跨越多行。
'''

JSDoc注释

• JSDoc 风格的注释通常以一个多行注释开始（/**），后跟一行或多行文本描述代码的功能，然后是一系列的 @ 标签，每个标签都描述了代码的某个方面。
  • JSDoc

    @param - 描述一个函数的参数。
    @returns 或 @return - 描述函数的返回值。
    @type - 指定一个变量或表达式的类型。
    @typedef - 定义一个新的类型。
    @property - 描述一个对象的属性，通常与 @typedef 一起使用。
    @class - 描述一个类。
    @constructor - 标识一个函数作为构造函数。
    @method - 描述一个类的方法。
    @example - 提供代码示例。
    @deprecated - 标记代码为已废弃。
    @see - 提供对其他文档或资源的引用。
    @throws 或 @exception - 描述函数可能抛出的错误或异常。
    @module - 描述一个模块。
    @namespace - 描述一个命名空间。
    @file 或 @fileoverview - 描述整个文件的作用或内容。
    @license - 指明代码的许可证信息。
    @private - 标记代码为私有成员。
    @public - 标记代码为公开成员。
    @protected - 标记代码为受保护的成员，仅在类及其子类中可见。
    @static - 标记方法或属性为静态的。
    @version - 指定代码的版本号。
    @author - 代码的作者。
    @todo - 指出还需要完成的任务或功能。

特殊标记注释（例如：Todo）

Note: 忽略大小写，可添加特殊符号，如 @
// TODO: 有功能代码待编写，待实现的功能在说明中会简略说明
// HOTFIX: 代码需要修正，甚至代码是错误的，不能工作，需要修复，如何修正会在说明中简略说明
// BUGFIX: BUGFIX 相关描述
// N.B. 特别说明(Note Bell)
// LINK_TO: 与此问题相关解决方案 or issue
// HACK: 编写得不好或格式错误，需要根据自己的需求去调整程序代码
// NOTE: 说明代码如何工作
// INFO: 相关信息描述
// TAG: Tag 相关描述

• 插件: TODO Tree
  

文件头部描述注释

• 文件头部注释通常位于源代码文件的最顶部，提供了文件的基本信息和概要，以及可能的版权和许可证信息。在很多编程语言中，包括JavaScript，头部注释可以使用多行注释语法来编写。

以下示例，展示了JavaScript文件头部的注释可能包含的内容：

/**
 * 文件名: example.js
 * 项目名称: Example Project
 * 文件创建日期: 2024-01-01
 * 作者: guying
 * 联系方式: guying@example.com
 *
 * 最后编辑日期: 2023-01-10
 * 最后编辑者: guying
 * 最后编辑者联系方式: guying@example.com
 *
 * 文件描述:
 * 这个文件提供了一个示例JavaScript模块，用于演示文件头部注释的结构。
 *
 * 许可证:
 * 本文件受 XYZ 许可证保护。使用前请确保你已经阅读许可条款，
 * 并且遵守所有相关条款。
 */

在某些情况下，你可能还会看到包含如下附加字段的文件头部注释：

@version - 标记文件的当前版本。
@license - 显示许可证的类型。
@author - 文件的原始作者。
@copyright - 版权声明。
@see - 提供相关文件、资源的链接。
@todo - 描述该文件的待办事项或计划中的更改。

文件头部注释的确切内容和格式会根据组织、团队或个人开发习惯而有所不同。它们有助于维护代码、跟踪版本历史和版权信息。在一些情况下（如开源项目），适当的文件头部注释是法律要求或许可证规定的一部分。

VSCode 快捷键

在 VSCode 中，你不必手动输入这些注释符号。你可以使用快捷键来快速添加或删除注释：

添加/删除单行注释

• 选择你想要注释的代码行，然后按下 Ctrl + / (Windows/Linux) 或 Cmd + / (macOS)。这会根据当前文件的语言自动添加或删除相应的单行注释符号。

添加/删除块注释（多行注释）

• 选择你想要注释的代码块，然后使用 Shift + Alt + A (Windows/Linux) 或 Shift + Option + A (macOS)。

这些快捷键非常方便，可以大幅提高编码效率。记住，注释应该是有意义的，它们应该帮助解释为什么代码是以某种方式编写的，而不只是说明它做了什么，这通常是代码本身就能告诉你的。

手动添加 JavaScript 的注释

在 Visual Studio Code (VSCode) 中，你可以手动添加 JavaScript 的注释，也可以使用扩展来生成更加详细和格式化的函数注释。以下是如何在 JS 中添加注释的基本方法，以及一个流行的扩展来帮助你生成函数注释。

• 手动添加注释
  在 JavaScript 中，你可以添加单行注释和多行注释：
  单行注释 使用 //:

  // 这是一个单行注释
  const x = 5;
  

  多行注释 使用 /* */:

  /*
    这是一个多行注释
    它可以覆盖多行代码
  */
  const y = 10;
  

• 手动添加函数注释
  • vscode中在函数名的上一行打/**，可以扩展JSDoc注释
    

    /**
     * 
     * @param a 
     * @param b 
     * @returns 
     */
    function sum(a, b) {
      return a + b;
    }
    

  • 当你在编写函数时，注释可以描述函数的目的、参数、返回值等。以下是一个简单的函数注释示例：

    /**
     * 计算两个数的和
     * @param {number} a 第一个加数
     * @param {number} b 第二个加数
     * @returns {number} 返回和
     */
    function sum(a, b) {
      return a + b;
    }
    

使用 VSCode 扩展

为了自动化和标准化函数注释的创建过程，你可以使用 VSCode 扩展，比如 Document This 或者 JSDoc 注释模板。以下是如何使用

Document This 扩展：

在 VSCode 中安装 Document This 扩展，可自动为TypeScript和JavaScript文件生成详细的JSDoc注释。

1. 编写你的 JavaScript 函数。
   将光标放到函数定义的上方或者函数名上。
   按下 Ctrl+Shift+P (Windows/Linux) 或 Cmd+Shift+P (macOS) 打开命令面板。
   输入 Document This 并选择它，扩展会自动在函数上方生成一个 JSDoc 风格的注释模板。
   这个模板通常包括函数描述、参数描述和返回值描述的占位符，你只需要填写实际的描述内容即可。
2. 将光标放到函数定义的上方或者函数名上，连续按两次Ctrl+Alt+D
   • 为插入符号所在或内部的内容生成文档。

  /**
   *
   *
   * @param {*} data
   * @param {*} error
   * @return {*} 
   */
  const handleSubmit = (data, error) => {
    if (error) return;
    setFormData(data);
  };

koroFileHeader扩展

用于一键生成文件头部注释并自动更新最后编辑人和编辑时间、函数注释自动生成和参数提取。
主要功能

自动生成文件头部注释，自动更新最后编辑人、最后编辑时间等。
一键生成函数注释，支持函数参数自动提取并列到注释中。
支持添加佛祖保佑永无bug、神兽护体、甩葱少女等好玩有趣的图像注释
配置非常灵活方便，各种细节都能配置，可以量身打造适合你的注释。
支持所有主流语言, 配置文档非常详细，齐全。

• vscode settings.json 扩展相关修改

    // 注释模板插件配置项
    "fileheader.configObj": {
      "autoAdd": false, // 检测文件没有头部注释，自动添加文件头部注释
      // 默认注释  没有匹配到注释符号的时候使用。
      "annotationStr": {
        "head": "<!--",
        "middle": "",
        "end": " -->",
        "use": true
      },
      "prohibitItemAutoAdd": [
        "项目的全称禁止项目自动添加头部注释, 使用快捷键自行添加"
      ]
    },
    // 头部注释
    "fileheader.customMade": {
      // 头部注释默认字段
      "FileDesc": "",
      "Author": "guying",
      "Date": "Do not edit", // 设置后默认设置文件生成时间
      // "LastEditTime": "Do not edit", // 设置后，保存文件更改默认更新最后编辑时间
      // "LastEditors": "liusheng", // 设置后，保存文件更改默认更新最后编辑人
      "Version": "",
      "Usage": "\n\t\t- template\n\t\t-\tjs\n\t\t- props\n\t\t- event\n\t\t- method"
      // "FilePath": "Do not edit", // 设置后，默认生成文件相对于项目的路径
      // "custom_string_obkoro1": "可以输入预定的版权声明、个性签名、空行等"
    },
    // 函数注释
    "fileheader.cursorMode": {
      // 默认字段
      "description": "",
      "param": "",
      "return": ""
    },
  

注释示例

1. 函数注释
   • 使用 JSDoc 风格注释来描述一个返回对象包含多个参数的函数
     • 在注释开始的地方添加描述，那么可省略 @description 标签。

     /**
      * 计算两数的和与积
      * @param {number} a 第一个数
      * @param {number} b 第二个数
      * @returns {{sum: number, product: number}} 返回包含和与积的对象
      */
     function compute(a, b) {
       return {
         sum: a + b,      // 和
         product: a * b   // 积
       };
     

   • 返回一个数组

     /**
     * 计算两数的和与积
     * @param {number} a 第一个数
     * @param {number} b 第二个数
     * @returns {[number, number]} 返回包含和与积的数组，第一个元素是和，第二个元素是积
     */
     function compute(a, b) {
      return [a + b, a * b]; // 数组的第一个元素是和，第二个元素是积
     }
     

2. 文件头部注释

   /**
    * @fileoverview 这个文件是项目的一部分，提供了特定功能的实现。
    * @author guying
    * @version 1.0.0
    * @license MIT
    *
    * 更多详细信息，例如函数的使用方法、实现的算法的描述，或者
    * 特定代码片段的解释，可以在该文件的相关部分找到。
    *
    * 示例项目版权信息
    * Copyright (c) 2023 guying. All rights reserved.
    *
    * 该源代码的使用受 MIT 许可证保护，该许可证随源代码提供。
    */
   

   /*
    * @FileDesc:
    * @Author: guying
    * @Date: 2024-02-28 16:46:52
    * @Version:
    * @Usage:
    * 		- template
    * 		-	js
    * 		- props
    * 		- event
    * 		- method
    */