转载自：码思途远

转载日期：2024年08月14日 广东

前言

在写代码过程中，是否看到那些大厂的代码写的注释都比较规范和漂亮，曾经的自己还在那里CV。修改代码都会涉及创建文件创建新的函数，但在这过程中，如何去规范或者丝滑去写好这部分，其实在代码的世界里面只要你好好应用好工具，一切都变得简单，因为工具会Auto，在这个过程中，你只需要去修改一点点东西既可。

插件1：koroFileHeader

采用插件1的效果：

文件注释效果：

函数注释效果：

出现快捷键不能用的问题：

按下ctrl+shift+p， 1.修改文件头快捷键：搜索fileheader，选择右侧设置图标，就进入按键绑定页面。2.修改函数注释快捷键：搜索cursorTip，选择右侧设置图标，就进入按键绑定页面。

Command

Keybinding

When

Source

fileheader

Ctrl+Alt+I

editorTextFocus

User

cursorTip

Ctrl+Alt+T

editorTextFocus

User

使用方法：

  • Ctrl+Alt+I将会插入文件头部注释；

  • Ctrl+Alt+T将会对当前鼠标函数位置所在函数进行函数注释；

在文件头部"fileheader.configObj"到"files.exclude"

settings 文件配置【配置还包含其他插件配置】：

该配置文件路径：

C:\Users\你的用户名\AppData\Roaming\Code\User\settings.json

{
  "cmake.configureOnOpen": true,
  "files.autoGuessEncoding": true,
  "editor.formatOnType": true,
  "[c]": {
      "editor.defaultFormatter": "ms-vscode.cpptools"
  },
  "security.workspace.trust.untrustedFiles": "open",
  "workbench.startupEditor": "none",
  "redhat.telemetry.enabled": true,
  "http.proxyAuthorization": null,
  "cSpell.languageSettings": [],
  "http.proxySupport": "on",
  "editor.inlineSuggest.enabled": true,
  "boot-java.rewrite.reconcile": true,
  "todohighlight.defaultStyle": {


  },
  "todohighlight.exclude": [

      "**/node_modules/**",
      "**/bower_components/**",
      "**/dist/**",
      "**/build/**",
      "**/.vscode/**",
      "**/.github/**",
      "**/_output/**",
      "**/*.min.*",
      "**/*.map",
      "**/.next/**"
  ],
  "fileheader.configObj": {
      "createFileTime": true,
      "language": {
          "languagetest": {
              "head": "/$$",
              "middle": " $ @",
              "end": " $/",
              "functionSymbol": {
                  "head": "/** ",
                  "middle": " * @",
                  "end": " */"
              },
              "functionParams": "js"
          }
      },
      "autoAdd": true,
      "autoAddLine": 100,
      "autoAlready": true,
      "annotationStr": {
          "head": "/*",
          "middle": " * @",
          "end": " */",
          "use": false
      },
      "headInsertLine": {
          "php": 2,
          "sh": 2
      },
      "beforeAnnotation": {
          "文件后缀": "该文件后缀的头部注释之前添加某些内容"
      },
      "afterAnnotation": {
          "文件后缀": "该文件后缀的头部注释之后添加某些内容"
      },
      "specialOptions": {
          "特殊字段": "自定义比如LastEditTime/LastEditors"
      },
      "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": false,
      "wideNum": 13,
      "functionWideNum": 0,
      "CheckFileChange": false,
      "createHeader": false,
      "useWorker": false,
      "designAddHead": false,
      "headDesignName": "random",
      "headDesign": false,
      "cursorModeInternalAll": {},
      "openFunctionParamsCheck": true,
      "functionParamsShape": [
          "{",
          "}"
      ],
      "functionBlankSpaceAll": {},
      "functionTypeSymbol": "*",
      "typeParamOrder": "type param",
      "customHasHeadEnd": {},
      "throttleTime": 10000,
      "functionParamAddStr": "",
      "NoMatchParams": "no show param"
  },
  "fileheader.cursorMode": {
      "function\t": "",
      "description\t": "", 
      "author\t": "git config user.name && git config user.email",   
      "param\t": "", 
      "return\t": "",
  },
  "fileheader.customMade": {
      "FileName": "${file_name}",
      "Description": "",
      "Author": "git config user.name && git config user.email",
      "Version": "v0.0.1",
      "Date": "Do not edit",
      "LastEditTime ": "Do not Edit",
      "custom_string_obkoro1_copyright": "Copyright ${now_year} HywelStar, All Rights Reserved. ", // 版权声明 保留所有权利 自动替换年份
      "custom_string_obkoro1_date": "Do not edit", // 版权时间
},
  "files.exclude": {
      "**/*.o": true
  },
  "github.copilot.editor.enableAutoCompletions": true,
  "STM32VSCodeExtension.projectCreator.executablePath": "f:\\Program Files\\STMicroelectronics\\STM32Cube\\STM32CubeMX\\STM32CubeMX.exe",
  "python.analysis.packageIndexDepths": [
      {
          "name": "sklearn",
          "depth": 2
      },
      {
          "name": "matplotlib",
          "depth": 2
      },
      {
          "name": "scipy",
          "depth": 2
      },
      {
          "name": "django",
          "depth": 2
      },
      {
          "name": "flask",
          "depth": 2
      },
      {
          "name": "fastapi",
          "depth": 2
      }
  ],
  "settingsSync.ignoredExtensions": [],
  "cSpell.userWords": [
      "Hywel"
  ],
  "remote.SSH.configFile": "G:\\Remote_ssh\\config",
  "remote.SSH.showLoginTerminal": true,
  "remote.SSH.remotePlatform": {
      "192.168.17.104": "linux"
  },
"C_Cpp.intelliSenseEngine": "disabled",
"diffEditor.ignoreTrimWhitespace": false
}

插件2：Doxygen Documentation Generator

效果文件头注释：

效果函数投注释：

setting.json 内容

当前setting.json 为项目的setting，可以改到

C:\Users\你的用户名\AppData\Roaming\Code\User\settings.json路径下


{
    "doxdocgen.file.copyrightTag": [
        "Copyright (C) 2024-2034 HywelStar.",
        "All rights reserved.",
        "",        
    ],

    "doxdocgen.file.customTag": [
        "@version\t v0.1",
        "",
        "@revision history:",
        "\t {date} - Initial version."
    ],

    "doxdocgen.file.fileTemplate": "@file \t Filename without the absolute path",
    "doxdocgen.generic.authorTag": "@author \t HywelStar(hywelstar@163.com)",
    "doxdocgen.generic.dateTemplate": "@date \t {date}",
    "doxdocgen.generic.briefTemplate": "@brief \t Brief description",
    "doxdocgen.generic.returnTemplate": "@return \t Description of return value",
    "doxdocgen.generic.paramTemplate": "@param \t {param} in/out \t Description of parameter",
    "doxdocgen.generic.customTags": [
        "@warning\t Special notes such as non-reentrancy, blocking issues, etc.",
        "@note\t Significant modifications"
    ],

    "doxdocgen.file.fileOrder": [
        "copyright",
        "", // New line
        "file",
        "brief",
        "author",
        "date",
        "custom"
    ],

    "doxdocgen.generic.order": [
        "brief",
        "param",
        "return",
        "custom"
    ],
    "C_Cpp.errorSquiggles": "enabled",
    "files.associations": {
        "*.def": "c"
    }
}

总结对比

本章节主要对对于使用vscode 平台使用文件头部和函数头部注释功能，选择上面任何一种都可以，不过笔者使用起来的感受的话，想要速度快一些可以采用第二种，对于第一种来说快捷键需要函数注释还是文件注释总是有些迟钝，但是第一种来说定制化和智能化会更高一些对时间修改都会有自动记录。对于团队合作看大家看中哪一种，方面后面代码一些规范化，采用同一种形态的注释也会更加完美一些。根据自身选择，简单就第二种，复杂化智能化就第一种。另外对于其他平台暂时还没有研究，对于老牌的source insight, eclipse 都有这样类似的设置方式。