注釋的意義
- 注釋可以幫我們很好的完成文檔的工作，寫得好的注釋可以方便我們以后的維護。
- /**/ 的塊注釋和 // 的單行注釋兩種注釋風格， 在我們的項目中為了風格的統一，全部使用單行注釋，注釋的質量決定了生成的文檔的質量。
- 下面從包注釋、結構體（接口）注釋、函數（方法）注釋、代碼邏輯注釋以及注釋規范方面進行說明。
包注釋
- 每個包都應該有一個包注釋，一個位於 package 子句之前行注釋
- 包注釋應該包含下面基本信息
// @Title 請填寫文件名稱（需要改）
// @Description 請填寫文件描述（需要改）
// @Author 請填寫自己的真是姓名（需要改） ${DATE} ${TIME}
// @Update 請填寫自己的真是姓名（需要改） ${DATE} ${TIME}
package ${GO_PACKAGE_NAME}
結構（接口）注釋
每個自定義的結構體或者接口都應該有注釋說明，該注釋對結構進行簡要介紹，放在結構體定義的前一行，格式為： 結構體名， 結構體說明。同時結構體內的每個成員變量都要有說明，該說明放在成員變量的后面（注意對齊），實例如下：
// User 用戶對象，定義了用戶的基礎信息
type User struct{
Username string // 用戶名
Email string // 郵箱
}
函數（方法）注釋
- 每個函數，或者方法（結構體或者接口下的函數稱為方法）都應該有注釋說明
- 函數的注釋應該包括三個方面
// @title 函數名稱
// @description 函數的詳細描述
// @auth 作者 時間（2019/6/18 10:57 ）
// @param 輸入參數名 參數類型 "解釋"
// @return 返回參數名 參數類型 "解釋"
代碼邏輯注釋
- 每個代碼塊都要添加單行注釋
- 注視使用 TODO 開始 詳細如下
// TODO 代碼塊的執行解釋
if userAge < 18 {
}
注釋要求
- 統一使用中文注釋，對於中英文字符之間嚴格使用空格分隔， 這個不僅僅是中文和英文之間，英文和中文標點之間也都要使用空格分隔
- 全部使用單行注釋，禁止使用多行注釋
- 和代碼的規范一樣，單行注釋不要過長，禁止超過 120 字符。
縮進和折行
- 縮進必須使用
gofmt工具格式化 - 折行方面，一行最長不超過 120 個字符，超過的請使用換行展示，盡量保持格式優雅
括號和空格
括號和空格方面，也可以直接使用 gofmt 工具格式化（go 會強制左大括號不換行，換行會報語法錯誤），所有的運算符和操作數之間要留空格。
import 規范
// 單行引入
import "fmt"
// 多包引入，每包獨占一行
// 使用絕對路徑，避免相對路徑如 ../encoding/json
import (
"strings"
"fmt"
)