VScode自动注释

编写程序的时候，经常需要规范化的注释以保证可读性，但手动注释非常的繁琐，而VScode可以通过一定的配置，自动生成相应的注释片段，本教程就展示了不那么详细的配置过程[手动狗头]。

头文件嵌入式框架格式生成

嵌入式每个头文件的框架采用如下格式（举例的头文件名字为ESPJarvis.h）：

#ifndef _ESPJARVIS_H 
#define _ESPJARVIS_H 
#ifdef __cplusplus
extern "C" {
#endif

...
头文件内容
...

#ifdef __cplusplus
}
#endif
#endif	// _ESPJARVIS_H

使用 #ifndef … #define … #endif 的目的在于避免重复调用头文件，其中_ESPJARVIS_H 是根据 _<文件名大写>_H_ 的格式。使用 #ifdef __cplusplus 可以增加对C++项目引用的支持，当在一个C++项目引用这个头文件时，编译器能知道要按照C语言对此文件进行编译。

这部分内容可以通过VScode的用户代码片段功能自动生成，操作方法如下：
选择文件->首选项->配置代码片段

选择新建全局代码片段，语言为C，这里我已经修改过了所以显示有所不同

此时会打开c.json配置文件，粘贴以下内容：

"Embedded_Global_snippet": {
	"prefix": "#ifndef",
	"body": [
		"#ifndef ${1:${TM_FILENAME_BASE/(.*)/_${1:/upcase}_H/i}}",
		"#define ${1:${TM_FILENAME_BASE/(.*)/_${1:/upcase}_H/i}}",
		"#ifdef __cplusplus",
		"extern \"C\" {",
		"#endif",
		"",
		"",
		"#ifdef __cplusplus",
		"}",
		"#endif",
		"#endif // $1"
	],
	"description": "Embedded_Global_snippet"
}

保存后即可在头文件输入#ifndef时自动补全：

如果你想自定义内容，可以前往这个网站生成：snippet generator

文件注释和函数注释

首先安装koroFileHeader插件，过程略。
右键插件，选择设置

点击在setting.json中设置

将下方的代码覆盖到此位置

"fileheader.configObj": {
    "createFileTime": true,
    "language": {
        "languagetest": {
            "head": "/$$",
            "middle": " $ @",
            "end": " $/",
            "functionSymbol": {
                "head": "/** ",
                "middle": " * @",
                "end": " */"
            },
            "functionParams": "js"
        },
        "h/hpp/cpp/c": {
        "head": "/** ", // 统一增加几个*号
        "middle": " * @",
        "end": " */"
        }
    },
    "autoAdd": true,
    "autoAddLine": 20,
    "autoAlready": true,
    "annotationStr": {
        "head": "/**",
        "middle": " * @",
        "end": " */",
        "use": false
    },
    "headInsertLine": {
        "php": 2,
        "sh": 2
    },
    "beforeAnnotation": {
        "文件后缀": "该文件后缀的头部注释之前添加某些内容"
    },
    "afterAnnotation": {
        "文件后缀": "该文件后缀的头部注释之后添加某些内容"
    },
    "specialOptions": {
        "Author": "author",
        "Date": "date",
        "LastEditTime": "last_edit",
        "Description": "brief", // 头部注释大写的描述Description
        "description": "brief", // 函数注释小写的描述：description
        "FilePath": "file"
        // 文件后缀、或者语言后缀，可针对单个文件后缀进行配置：language的自定义语言配置
    },
    "switch": {
        "newlineAddAnnotation": true
    },
    "supportAutoLanguage": [],
    "prohibitAutoAdd": [
        "json"
    ],
    "folderBlacklist": [
        "node_modules",
        "文件夹禁止自动添加头部注释"
    ],
    "prohibitItemAutoAdd": [
        "项目的全称, 整个项目禁止自动添加头部注释, 可以使用快捷键添加"
    ],
    "moveCursor": true,
    "dateFormat": "YYYY-MM-DD HH:mm:ss",
    "atSymbol": [
        "@",
        "@"
    ],
    "atSymbolObj": {
        "文件后缀": [
            "头部注释@符号",
            "函数注释@符号"
        ]
    },
    "colon": [
        ": ",
        ": "
    ],
    "colonObj": {
        "文件后缀": [
            "头部注释冒号",
            "函数注释冒号"
        ]
    },
    "filePathColon": "路径分隔符替换",
    "showErrorMessage": false,
    "writeLog": false,
    "wideSame": true,
    "wideNum": 10,
    "functionWideNum": 10,
    "CheckFileChange": false,
    "createHeader": false,
    "useWorker": false,
    "designAddHead": false,
    "headDesignName": "random",
    "headDesign": false,
    "cursorModeInternalAll": {},
    "openFunctionParamsCheck": true,
    "functionParamsShape": [
        "{",
        "}"
    ],
    "functionBlankSpaceAll": {},
    "functionTypeSymbol": "*",
    "typeParamOrder": "type param",
    "customHasHeadEnd": {},
    "throttleTime": 60000,
    "functionParamAddStr": "",
    "NoMatchParams": "no show param"
},
// 头部注释
"fileheader.customMade": {
    // Author字段是文件的创建者 可以在specialOptions中更改特殊属性
    // 公司项目和个人项目可以配置不同的用户名与邮箱 搜索: gitconfig includeIf  比如: https://ayase.moe/2021/03/09/customized-git-config/
    // 自动提取当前git config中的: 用户名、邮箱
    // "Author": "git config user.name && git config user.email", // 同时获取用户名与邮箱
    // "Author": "git config user.name", // 仅获取用户名
    // "Author": "git config user.email", // 仅获取邮箱
    "Author": "yourname", // 写死的固定值 不从git config中获取
    "Date": "Do not edit", // 文件创建时间(不变)
    // LastEditors、LastEditTime、FilePath将会自动更新 如果觉得时间更新的太频繁可以使用throttleTime(默认为1分钟)配置更改更新时间。
    // "LastEditors": "yourname", // 文件最后编辑者 与Author字段一致
    // 由于编辑文件就会变更最后编辑时间，多人协作中合并的时候会导致merge
    // 可以将时间颗粒度改为周、或者月，这样冲突就减少很多。搜索变更时间格式: dateFormat
    "LastEditTime": "Do not edit", // 文件最后编辑时间
    // 输出相对路径，类似: /文件夹名称/src/index.js
    "FilePath": "only file name", // 文件在项目中的相对路径 自动更新
    // 插件会自动将光标移动到Description选项中 方便输入 Description字段可以在specialOptions更改
    "Description": "", // 介绍文件的作用、文件的入参、出参。
    // custom_string_obkoro1~custom_string_obkoro100都可以输出自定义信息
    // 可以设置多条自定义信息 设置个性签名、留下QQ、微信联系方式、输入空行等
    // "custom_string_obkoro1": "", 
    // 版权声明 保留文件所有权利 自动替换年份 获取git配置的用户名和邮箱
    // 版权声明获取git配置, 与Author字段一致: ${git_name} ${git_email} ${git_name_email}
    "custom_string_obkoro1_copyright": "Copyright (c) ${now_year} by yourname, All Rights Reserved. "
    // "custom_string_obkoro1_copyright": "Copyright (c) ${now_year} by 写死的公司名/用户名, All Rights Reserved. "
},
// 函数注释
"fileheader.cursorMode": {
    "description": "", // 函数注释生成之后，光标移动到这里
    "param": "", // param 开启函数参数自动提取 需要将光标放在函数行或者函数上方的空白行
    "return": "",
}

之后使用快捷键Ctrl+Win+i和Ctrl+Win+t即可分别生成文件注释和函数注释：

如果你想更详细的了解插件配置方式，可前往此处：https://github.com/OBKoro1/koro1FileHeader/wiki/%E9%85%8D%E7%BD%AE

参考文章：
嵌入式开发中的一些代码规范和风格
vsCode设置用户代码片段
【vscode】生成函数参数@param注释 及 自动添加头注释和函数注释