Go語言代碼規範指導

本規範旨在爲平常Go項目開發提供一個代碼的規範指導，方便團隊造成一個統一的代碼風格，提升代碼的可讀性，規範性和統一性。本規範將從命名規範，註釋規範，代碼風格和 Go 語言提供的經常使用的工具這幾個方面作一個說明。該規範參考了 go 語言官方代碼的風格制定。

1、 命名規範

命名是代碼規範中很重要的一部分，統一的命名規則有利於提升的代碼的可讀性，好的命名僅僅經過命名就能夠獲取到足夠多的信息。

Go在命名時以字母a到Z或a到Z或下劃線開頭，後面跟着零或更多的字母、下劃線和數字(0到9)。Go不容許在命名時中使用@、$和%等標點符號。Go是一種區分大小寫的編程語言。所以，Manpower和manpower是兩個不一樣的命名。

1. 當命名（包括常量、變量、類型、函數名、結構字段等等）以一個大寫字母開頭，如：Group1，那麼使用這種形式的標識符的對象就能夠被外部包的代碼所使用（客戶端程序須要先導入這個包），這被稱爲導出（像面嚮對象語言中的 public）；
2. 命名若是以小寫字母開頭，則對包外是不可見的，可是他們在整個包的內部是可見而且可用的（像面嚮對象語言中的 private ）

一、包命名：package

保持package的名字和目錄保持一致，儘可能採起有意義的包名，簡短，有意義，儘可能和標準庫不要衝突。包名應該爲小寫單詞，不要使用下劃線或者混合大小寫。

package demo
​
package main

二、 文件命名

儘可能採起有意義的文件名，簡短，有意義，應該爲小寫單詞，使用下劃線分隔各個單詞。

my_test.go

三、 結構體命名

• 採用駝峯命名法，首字母根據訪問控制大寫或者小寫
• struct 申明和初始化格式採用多行，例以下面：

// 多行申明
type User struct{
    Username  string
    Email     string
}
​
// 多行初始化
u := User{
    Username: "astaxie",
    Email:    "astaxie@gmail.com",
}

四、 接口命名

• 命名規則基本和上面的結構體類型
• 單個函數的結構名以 「er」 做爲後綴，例如 Reader , Writer 。

type Reader interface {
        Read(p []byte) (n int, err error)
}

五、變量命名

• 和結構體相似，變量名稱通常遵循駝峯法，首字母根據訪問控制原則大寫或者小寫，但遇到特有名詞時，須要遵循如下規則： 
• 若是變量爲私有，且特有名詞爲首個單詞，則使用小寫，如 apiClient
• 其它狀況都應當使用該名詞原有的寫法，如 APIClient、repoID、UserID
• 錯誤示例：UrlArray，應該寫成 urlArray 或者 URLArray
• 若變量類型爲 bool 類型，則名稱應以 Has, Is, Can 或 Allow 開頭

var isExist bool
var hasConflict bool
var canManage bool
var allowGitHook bool

六、常量命名

常量均需使用所有大寫字母組成，並使用下劃線分詞

const APP_VER = "1.0"

若是是枚舉類型的常量，須要先建立相應類型：

type Scheme string
​
const (
    HTTP  Scheme = "http"
    HTTPS Scheme = "https"
)

七、 關鍵字

下面的列表顯示了Go中的保留字。這些保留字不能用做常量或變量或任何其餘標識符名稱

2、註釋

Go提供C風格的/* */塊註釋和C ++風格的//行註釋。行註釋是常態；塊註釋主要顯示爲包註釋，但在表達式中頗有用或禁用大量代碼。

• 單行註釋是最多見的註釋形式，你能夠在任何地方使用以 // 開頭的單行註釋
• 多行註釋也叫塊註釋，均已以 /* 開頭，並以 */ 結尾，且不能夠嵌套使用，多行註釋通常用於包的文檔描述或註釋成塊的代碼片斷

go 語言自帶的 godoc 工具能夠根據註釋生成文檔，生成能夠自動生成對應的網站（ http://golang.org就是使用 godoc 工具直接生成的），註釋的質量決定了生成的文檔的質量。每一個包都應該有一個包註釋，在package子句以前有一個塊註釋。對於多文件包，包註釋只須要存在於一個文件中，任何一個均可以。包評論應該介紹包，並提供與整個包相關的信息。它將首先出如今godoc頁面上，並應設置下面的詳細文檔。

詳細的如何寫註釋能夠 參考：http://golang.org/doc/effective_go.html#commentary

一、包註釋

每一個包都應該有一個包註釋，一個位於package子句以前的塊註釋或行註釋。包若是有多個go文件，只須要出如今一個go文件中（通常是和包同名的文件）便可。 包註釋應該包含下面基本信息(請嚴格按照這個順序，簡介，建立人，建立時間）：

• 包的基本簡介（包名，簡介）
• 建立者，格式： 建立人： rtx 名
• 建立時間，格式：建立時間： yyyyMMdd

例如 util 包的註釋示例以下

// util 包， 該包包含了項目共用的一些常量，封裝了項目中一些共用函數。
// 建立人： hanru
// 建立時間： 20190419

二、結構（接口）註釋

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

// User ， 用戶對象，定義了用戶的基礎信息
type User struct{
    Username  string // 用戶名
    Email     string // 郵箱
}

三、函數（方法）註釋

每一個函數，或者方法（結構體或者接口下的函數稱爲方法）都應該有註釋說明，函數的註釋應該包括三個方面（嚴格按照此順序撰寫）：

• 簡要說明，格式說明：以函數名開頭，「，」分隔說明部分
• 參數列表：每行一個參數，參數名開頭，「，」分隔說明部分
• 返回值： 每行一個返回值

示例以下：

// NewtAttrModel ， 屬性數據層操做類的工廠方法
// 參數：
//      ctx ： 上下文信息
// 返回值：
//      屬性操做類指針
func NewAttrModel(ctx *common.Context) *AttrModel {
}

四、代碼邏輯註釋

對於一些關鍵位置的代碼邏輯，或者局部較爲複雜的邏輯，須要有相應的邏輯說明，方便其餘開發者閱讀該段代碼，實例以下：

// 從 Redis 中批量讀取屬性，對於沒有讀取到的 id ， 記錄到一個數組裏面，準備從 DB 中讀取
xxxxx
xxxxxxx
xxxxxxx

五、註釋風格

統一使用中文註釋，對於中英文字符之間嚴格使用空格分隔， 這個不只僅是中文和英文之間，英文和中文標點之間也都要使用空格分隔，例如：

// 從 Redis 中批量讀取屬性，對於沒有讀取到的 id ， 記錄到一個數組裏面，準備從 DB 中讀取

上面 Redis 、 id 、 DB 和其餘中文字符之間都是用了空格分隔。

• 建議所有使用單行註釋
• 和代碼的規範同樣，單行註釋不要過長，禁止超過 120 字符。

3、代碼風格

一、縮進和折行

• 縮進直接使用 gofmt 工具格式化便可（gofmt 是使用 tab 縮進的）；
• 折行方面，一行最長不超過120個字符，超過的請使用換行展現，儘可能保持格式優雅。

咱們使用Goland開發工具，能夠直接使用快捷鍵：ctrl+alt+L，便可。

二、語句的結尾

Go語言中是不須要相似於Java須要冒號結尾，默認一行就是一條數據

若是你打算將多個語句寫在同一行，它們則必須使用 ;

三、括號和空格

括號和空格方面，也能夠直接使用 gofmt 工具格式化（go 會強制左大括號不換行，換行會報語法錯誤），全部的運算符和操做數之間要留空格。

// 正確的方式
if a > 0 {
​
} 
​
// 錯誤的方式
if a>0  // a ，0 和 > 之間應該空格
{       // 左大括號不能夠換行，會報語法錯誤
​
}
​

四、import 規範

import在多行的狀況下，goimports會自動幫你格式化，可是咱們這裏仍是規範一下import的一些規範，若是你在一個文件裏面引入了一個package，仍是建議採用以下格式：

import (
    "fmt"
)

若是你的包引入了三種類型的包，標準庫包，程序內部包，第三方包，建議採用以下方式進行組織你的包：

import (
    "encoding/json"
    "strings"
​
    "myproject/models"
    "myproject/controller"
    "myproject/utils"
​
    "github.com/astaxie/beego"
    "github.com/go-sql-driver/mysql"
)   

有順序的引入包，不一樣的類型採用空格分離，第一種實標準庫，第二是項目包，第三是第三方包。

在項目中不要使用相對路徑引入包：

// 這是很差的導入
import 「../net」
​
// 這是正確的作法
import 「github.com/repo/proj/src/net」

可是若是是引入本項目中的其餘包，最好使用相對路徑。

五、錯誤處理

• 錯誤處理的原則就是不能丟棄任何有返回err的調用，不要使用 _ 丟棄，必須所有處理。接收到錯誤，要麼返回err，或者使用log記錄下來
• 儘早return：一旦有錯誤發生，立刻返回
• 儘可能不要使用panic，除非你知道你在作什麼
• 錯誤描述若是是英文必須爲小寫，不須要標點結尾
• 採用獨立的錯誤流進行處理

// 錯誤寫法
if err != nil {
    // error handling
} else {
    // normal code
}
​
// 正確寫法
if err != nil {
    // error handling
    return // or continue, etc.
}
// normal code
​

六、測試

單元測試文件名命名規範爲 example_test.go 測試用例的函數名稱必須以 Test 開頭，例如：TestExample 每一個重要的函數都要首先編寫測試用例，測試用例和正規代碼一塊兒提交方便進行迴歸測試

4、經常使用工具

上面提到了很過規範， go 語言自己在代碼規範性這方面也作了不少努力，不少限制都是強制語法要求，例如左大括號不換行，引用的包或者定義的變量不使用會報錯，此外 go 仍是提供了不少好用的工具幫助咱們進行代碼的規範，

gofmt 大部分的格式問題能夠經過gofmt解決， gofmt 自動格式化代碼，保證全部的 go 代碼與官方推薦的格式保持一致，因而全部格式有關問題，都以 gofmt 的結果爲準。

goimport 咱們強烈建議使用 goimport ，該工具在 gofmt 的基礎上增長了自動刪除和引入包.

go get golang.org/x/tools/cmd/goimports

go vet vet工具能夠幫咱們靜態分析咱們的源碼存在的各類問題，例如多餘的代碼，提早return的邏輯，struct的tag是否符合標準等。

go get golang.org/x/tools/cmd/vet

使用以下：

go vet .