文章目錄
- 前言
- 一、koroFileHeader是什么？
- 二、使用步驟
- 1.安裝
- 1.配置
- 2.食用
前言
今天的天氣還不錯，真是金風玉露一相逢，便勝卻人間無數，寫篇博客玩玩，主題：注釋。注釋的本質就是對代碼的解釋和說明，目的是為了讓別人和自己很容易看懂，一看就知道這段代碼是做什么用的，提升代碼的可讀性和可維護性，畢竟需求不是一成不變的，不停的變更或者迭代就要求代碼具備易于維護的特點。正確的程序注釋一般包括序言性注釋和功能性注釋，序言性注釋的主要內容包括模塊的接口、數據的描述和模塊的功能。功能性注釋的主要內容包括程序段的功能、語句的功能和數據的狀態。注釋主要分為行注釋和塊注釋，也包括文件的注釋（文件的說明）。不同的語言有不同的注釋格式。
一、koroFileHeader是什么？
- 用于一鍵生成文件頭部注釋并自動更新最后編輯人和編輯時間、函數注釋自動生成和參數提取。
- 插件可以幫助用戶養成良好的編碼習慣，規范整個團隊風格。
- 從2018年5月維護至今, 關閉issue 500+ ，擁有39.7w+的用戶，VSCode圖表統計日均安裝200-500
- 經過多版迭代后，插件支持所有主流語言,靈活方便，文檔齊全，食用簡單！
二、使用步驟
1.安裝
- 直接在編輯器里面搜索安裝。
- 下載插件安裝【Install from VSIX】
下載.vsix文件，有的人沒有外網，就需要通過這種方式安裝。
鏈接: 下載.vsix文件
下載頁面如下：
1.配置
配置頭部注釋模板與函數注釋模板
- 復制下面的模板插入到vscode編輯器的全局設置(setting.json)中。
- 重啟編輯器
模板如下：
// 頭部注釋
"fileheader.customMade": {// 頭部注釋默認字段"Author": "your name","Date": "Do not edit", // 設置后默認設置文件生成時間"LastEditTime": "Do not edit", // 設置后，保存文件更改默認更新最后編輯時間"LastEditors": "your name", // 設置后，保存文件更改默認更新最后編輯人"Description": "","FilePath": "Do not edit", // 設置后，默認生成文件相對于項目的路徑"custom_string_obkoro1": "可以輸入預定的版權聲明、個性簽名、空行等"
},
// 函數注釋
"fileheader.cursorMode": {// 默認字段"description":"","param":"","return":""
},
// 插件配置項
"fileheader.configObj": {"autoAdd": true, // 檢測文件沒有頭部注釋，自動添加文件頭部注釋"autoAddLine": 100, // 文件超過多少行數 不再自動添加頭部注釋"autoAlready": true, // 只添加插件支持的語言以及用戶通過`language`選項自定義的注釋"supportAutoLanguage": [], // 設置之后，在數組內的文件才支持自動添加// 自動添加頭部注釋黑名單"prohibitAutoAdd": ["json"],"prohibitItemAutoAdd": [ "項目的全稱禁止項目自動添加頭部注釋, 使用快捷鍵自行添加" ],"folderBlacklist": [ "node_modules" ], // 文件夾或文件名禁止自動添加頭部注釋"wideSame": false, // 頭部注釋等寬設置"wideNum": 13, // 頭部注釋字段長度 默認為13"functionWideNum": 0, // 函數注釋等寬設置 設為0 即為關閉// 頭部注釋第幾行插入"headInsertLine": {"php": 2 // php文件 插入到第二行},"beforeAnnotation": {}, // 頭部注釋之前插入內容"afterAnnotation": {}, // 頭部注釋之后插入內容"specialOptions": {}, // 特殊字段自定義"switch": {"newlineAddAnnotation": true // 默認遇到換行符(\r\n \n \r)添加注釋符號},"moveCursor": true, // 自動移動光標到Description所在行"dateFormat": "YYYY-MM-DD HH:mm:ss","atSymbol": ["@", "@"], // 更改所有文件的自定義注釋中的@符號"atSymbolObj": {}, // 更改單獨語言/文件的@"colon": [": ", ": "], // 更改所有文件的注釋冒號"colonObj": {}, // 更改單獨語言/文件的冒號"filePathColon": "路徑分隔符替換", // 默認值： mac: / window是: \"showErrorMessage": false, // 是否顯示插件錯誤通知 用于debugger"writeLog": false, // 錯誤日志生成"CheckFileChange": false, // 單個文件保存時進行diff檢查"createHeader": true, // 新建文件自動添加頭部注釋"useWorker": false, // 是否使用工作區設置"designAddHead": false, // 添加注釋圖案時添加頭部注釋"headDesignName": "random", // 圖案注釋使用哪個圖案 "headDesign": false, // 是否使用圖案注釋替換頭部注釋// 自定義配置是否在函數內生成注釋 不同文件類型和語言類型"cursorModeInternalAll": {}, // 默認為false 在函數外生成函數注釋"openFunctionParamsCheck": true, // 開啟關閉自動提取添加函數參數"functionParamsShape": ["{", "}"], // 函數參數外形自定義 // "functionParamsShape": "no type" 函數參數不需要類型"functionBlankSpaceAll": {}, // 函數注釋空格縮進 默認為空對象 默認值為0 不縮進"functionTypeSymbol": "*", // 參數沒有類型時的默認值"typeParamOrder": "type param", // 參數類型 和 參數的位置自定義// 自定義語言注釋，自定義取消 head、end 部分// 不設置自定義配置language無效 默認都有head、end"customHasHeadEnd": {}, // "cancel head and function" | "cancel head" | "cancel function" "throttleTime": 60000, // 對同一個文件 需要過1分鐘再次修改文件并保存才會更新注釋// 自定義語言注釋符號，覆蓋插件的注釋格式"language": {// js后綴文件"js": {"head": "/$$","middle": " $ @","end": " $/",// 函數自定義注釋符號：如果有此配置 會默認使用"functionSymbol": {"head": "/******* ", // 統一增加幾個*號"middle": " * @","end": " */"},"functionParams": "typescript" // 函數注釋使用ts語言的解析邏輯},// 一次匹配多種文件后綴文件 不用重復設置"h/hpp/cpp": {"head": "/*** ", // 統一增加幾個*號"middle": " * @","end": " */"},// 針對有特殊要求的文件如：test.blade.php"blade.php":{"head": "<!--","middle": " * @","end": "-->",}},// 默認注釋 沒有匹配到注釋符號的時候使用。"annotationStr": { "head": "/*","middle": " * @","end": " */","use": false},
}
如何找到setting.json？
- 輸命令打開
- mac: command + p
- window: ctrl + p
- 輸入> Open Settings(注意>后面有一個空格)
或者直接點設置按鈕打開，這個是我喜歡的方式。
2.食用
- 文件頭部注釋快捷鍵
- window：ctrl+win+i
- mac：ctrl+cmd+i
- linux: ctrl+meta+i
- Ubuntu: ctrl+super+i
- 函數注釋注釋快捷鍵【將光標放在函數行或者將光標放在函數上方的空白行。】
- window：ctrl+win+t
- mac：ctrl+cmd+t
- linux: ctrl+meta+t
- Ubuntu: ctrl+super+t
