golang 註釋規範

註釋的意義[#]

• 註釋可以幫我們很好的完成文件的工作，寫得好的註釋可以方便我們以後的維護。
• /**/ 的塊註釋和 // 的單行註釋兩種註釋風格， 在我們的專案中為了風格的統一，全部使用單行註釋，註釋的質量決定了生成的文件的質量。
• 下面從包註釋、結構體（介面）註釋、函式（方法）註釋、程式碼邏輯註釋以及註釋規範方面進行說明。

包註釋[#]

• 每個包都應該有一個包註釋，一個位於 package 子句之前行註釋
• 包註釋應該包含下面基本資訊

Copy

// @Title 請填寫檔名稱（需要改） // @Description 請填寫檔案描述（需要改） // @Author 請填寫自己的真是姓名（需要改） ${DATE} ${TIME} // @Update 請填寫自己的真是姓名（需要改） ${DATE} ${TIME} package ${GO_PACKAGE_NAME}

結構（介面）註釋

每個自定義的結構體或者介面都應該有註釋說明，該註釋對結構進行簡要介紹，放在結構體定義的前一行，格式為： 結構體名， 結構體說明。同時結構體內的每個成員變數都要有說明，該說明放在成員變數的後面（注意對齊），例項如下：

type User struct{
    Username  string // 使用者名稱
    Email     string // 郵箱
}

函式（方法）註釋

• 每個函式，或者方法（結構體或者介面下的函式稱為方法）都應該有註釋說明
• 函式的註釋應該包括三個方面

// @description   函式的詳細描述
// @auth      作者             時間（2019/6/18   10:57 ）
// @param     輸入引數名        引數型別         "解釋"
// @return    返回引數名        引數型別         "解釋"` 

程式碼邏輯註釋

• 每個程式碼塊都要新增單行註釋
• 注視使用 TODO 開始 詳細如下

if   userAge < 18 {

}

註釋要求

• 統一使用中文註釋，對於中英文字元之間嚴格使用空格分隔， 這個不僅僅是中文和英文之間，英文和中文標點之間也都要使用空格分隔
• 全部使用單行註釋，禁止使用多行註釋
• 和程式碼的規範一樣，單行註釋不要過長，禁止超過 120 字元。

縮排和折行

• 縮排必須使用 gofmt 工具格式化
• 折行方面，一行最長不超過 120 個字元，超過的請使用換行展示，儘量保持格式優雅

括號和空格

括號和空格方面，也可以直接使用 gofmt 工具格式化（go 會強制左大括號不換行，換行會報語法錯誤），所有的運算子和運算元之間要留空格。

import 規範

import  "fmt"` 

Copy

// 多包引入，每包獨佔一行
// 使用絕對路徑，避免相對路徑如 ../encoding/json
import (
     "strings"
     "fmt"
)

原文連結：www.cnblogs.com/zhichaoma/p/125099...

本作品採用《CC 協議》，轉載必須註明作者和本文連結