注釋的意義
- 注釋可以幫我們很好的完成文檔的工作，寫得好的注釋可以方便我們以后的維護蓝撇。
- /**/ 的塊注釋和 // 的單行注釋兩種注釋風(fēng)格， 在我們的項目中為了風(fēng)格的統(tǒng)一，全部使用單行注釋丝蹭，注釋的質(zhì)量決定了生成的文檔的質(zhì)量。
- 下面從包注釋坪蚁、結(jié)構(gòu)體（接口）注釋奔穿、函數(shù)（方法）注釋镜沽、代碼邏輯注釋以及注釋規(guī)范方面進行說明。
包注釋
- 每個包都應(yīng)該有一個包注釋贱田，一個位于package子句之前行注釋
- 包注釋應(yīng)該包含下面基本信息
// @Title 請?zhí)顚懳募Q（需要改）
// @Description 請?zhí)顚懳募枋觯ㄐ枰模?// @Author 請?zhí)顚懽约旱恼媸切彰ㄐ枰模? ${DATE} ${TIME}
// @Update 請?zhí)顚懽约旱恼媸切彰ㄐ枰模? ${DATE} ${TIME}
package ${GO_PACKAGE_NAME}
結(jié)構(gòu)（接口）注釋
每個自定義的結(jié)構(gòu)體或者接口都應(yīng)該有注釋說明缅茉，該注釋對結(jié)構(gòu)進行簡要介紹，放在結(jié)構(gòu)體定義的前一行男摧，格式為： 結(jié)構(gòu)體名蔬墩， 結(jié)構(gòu)體說明。同時結(jié)構(gòu)體內(nèi)的每個成員變量都要有說明耗拓，該說明放在成員變量的后面（注意對齊）拇颅，實例如下：
// User 用戶對象，定義了用戶的基礎(chǔ)信息
type User struct{
Username string // 用戶名
Email string // 郵箱
}
函數(shù)（方法）注釋
- 每個函數(shù)乔询，或者方法（結(jié)構(gòu)體或者接口下的函數(shù)稱為方法）都應(yīng)該有注釋說明
- 函數(shù)的注釋應(yīng)該包括三個方面
// @title 函數(shù)名稱
// @description 函數(shù)的詳細描述
// @auth 作者 時間（2019/6/18 10:57 ）
// @param 輸入?yún)?shù)名 參數(shù)類型 "解釋"
// @return 返回參數(shù)名 參數(shù)類型 "解釋"
代碼邏輯注釋
- 每個代碼塊都要添加單行注釋
- 注視使用TODO 開始 詳細如下
// TODO 代碼塊的執(zhí)行解釋
if userAge < 18 {
}
注釋要求
- 統(tǒng)一使用中文注釋樟插，對于中英文字符之間嚴格使用空格分隔， 這個不僅僅是中文和英文之間竿刁，英文和中文標(biāo)點之間也都要使用空格分隔
- 全部使用單行注釋黄锤，禁止使用多行注釋
- 和代碼的規(guī)范一樣，單行注釋不要過長们妥，禁止超過 120 字符猜扮。
縮進和折行
- 縮進必須使用 gofmt 工具格式化
- 折行方面，一行最長不超過120個字符监婶，超過的請使用換行展示旅赢，盡量保持格式優(yōu)雅
括號和空格
括號和空格方面，也可以直接使用 gofmt 工具格式化（go 會強制左大括號不換行惑惶，換行會報語法錯誤）煮盼，所有的運算符和操作數(shù)之間要留空格。
import 規(guī)范
// 單行引入
import "fmt"
// 多包引入带污，每包獨占一行
// 使用絕對路徑僵控，避免相對路徑如 ../encoding/json
import (
"strings"
"fmt"
)
