盤一盤 Go 語言中的編碼規(guī)范

回復(fù)“Go語言”即可獲贈Python從入門到進(jìn)階共10本電子書

本文根據(jù)個人編碼習(xí)慣以及網(wǎng)絡(luò)上的一些文章，整理了一些大家能用上的編碼規(guī)范，可能是一些主流方案，但不代表官方，這一點(diǎn)先聲明一下。

1. 文件命名

1. 由于 Windows平臺文件名不區(qū)分大小寫，所以文件名應(yīng)一律使用小寫

2. 不同單詞之間用下劃線分詞，不要使用駝峰式命名

3. 如果是測試文件，可以以 _test.go 結(jié)尾

4. 文件若具有平臺特性，應(yīng)以 文件名_平臺.go 命名，比如 utils_ windows.go，utils_linux.go，可用的平臺有：windows, unix, posix, plan9, darwin, bsd, linux, freebsd, nacl, netbsd, openbsd, solaris, dragonfly, bsd, notbsd， android，stubs

5. 一般情況下應(yīng)用的主入口應(yīng)為 main.go，或者以應(yīng)用的全小寫形式命名。比如MyBlog 的入口可以為 myblog.go

2. 常量命名

目前在網(wǎng)絡(luò)上可以看到主要有兩種風(fēng)格的寫法

1. 第一種是駝峰命名法，比如 appVersion

2. 第二種使用全大寫且用下劃線分詞，比如 APP_VERSION

這兩種風(fēng)格，沒有孰好孰弱，可自由選取，我個人更傾向于使用第二種，主要是能一眼與變量區(qū)分開來。

如果要定義多個變量，請使用 括號 來組織。

const?(
? APP_VERSION?=?"0.1.0"
??CONF_PATH?=?"/etc/xx.conf"
)

3. 變量命名

和常量不同，變量的命名，開發(fā)者們的喜好就比較一致了，統(tǒng)一使用 駝峰命名法

1. 在相對簡單的環(huán)境（對象數(shù)量少、針對性強(qiáng)）中，可以將完整單詞簡寫為單個字母，例如：user寫為u

2. 若該變量為 bool 類型，則名稱應(yīng)以 Has, Is, Can 或 Allow 開頭。例如：isExist ，hasConflict 。

3. 其他一般情況下首單詞全小寫，其后各單詞首字母大寫。例如：numShips 和 startDate 。

4. 若變量中有特有名詞（以下列出），且變量為私有，則首單詞還是使用全小寫，如 apiClient。

5. 若變量中有特有名詞（以下列出），但變量不是私有，那首單詞就要變成全大寫。例如：APIClient，URLString

這里列舉了一些常見的特有名詞：

//?A?GonicMapper?that?contains?a?list?of?common?initialisms?taken?from?golang/lint
var?LintGonicMapper?=?GonicMapper{
????"API":???true,
????"ASCII":?true,
????"CPU":???true,
????"CSS":???true,
????"DNS":???true,
????"EOF":???true,
????"GUID":??true,
????"HTML":??true,
????"HTTP":??true,
????"HTTPS":?true,
????"ID":????true,
????"IP":????true,
????"JSON":??true,
????"LHS":???true,
????"QPS":???true,
????"RAM":???true,
????"RHS":???true,
????"RPC":???true,
????"SLA":???true,
????"SMTP":??true,
????"SSH":???true,
????"TLS":???true,
????"TTL":???true,
????"UI":????true,
????"UID":???true,
????"UUID":??true,
????"URI":???true,
????"URL":???true,
????"UTF8":??true,
????"VM":????true,
????"XML":???true,
????"XSRF":??true,
????"XSS":???true,
}

4. 函數(shù)命名

1. 函數(shù)名還是使用 駝峰命名法

2. 但是有一點(diǎn)需要注意，在 Golang 中是用大小寫來控制函數(shù)的可見性，因此當(dāng)你需要在包外訪問，請使用 大寫字母開頭

3. 當(dāng)你不需要在包外訪問，請使用小寫字母開頭

另外，函數(shù)內(nèi)部的參數(shù)的排列順序也有幾點(diǎn)原則

1. 參數(shù)的重要程度越高，應(yīng)排在越前面

2. 簡單的類型應(yīng)優(yōu)先復(fù)雜類型

3. 盡可能將同種類型的參數(shù)放在相鄰位置，則只需寫一次類型

5. 接口命名

使用駝峰命名法，可以用 type alias 來定義大寫開頭的 type ?給包外訪問。

type?helloWorld?interface?{
????func?Hello();
}

type?SayHello?helloWorld

當(dāng)你的接口只有一個函數(shù)時，接口名通常會以 er 為后綴

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

5. 注釋規(guī)范

注釋分為

5.1 包注釋

1. 位于 package 之前，如果一個包有多個文件，只需要在一個文件中編寫即可

2. 如果你想在每個文件中的頭部加上注釋，需要在版權(quán)注釋和 Package前面加一個空行，否則版權(quán)注釋會作為Package的注釋。

//?Copyright?2009?The?Go?Authors.?All?rights?reserved.
//?Use?of?this?source?code?is?governed?by?a?BSD-style
//?license?that?can?be?found?in?the?LICENSE?file.
package?net

3. 如果是特別復(fù)雜的包，可單獨(dú)創(chuàng)建 doc.go 文件說明

5.2 代碼注釋

用于解釋代碼邏輯，可以有兩種寫法

單行注釋使用 // ，多行注釋使用 /* comment */

//?單行注釋

/*
多
行
注
釋
*/

另外，對于代碼注釋還有一些更加苛刻的要求，這個看個人了，摘自網(wǎng)絡(luò)：

• 所有導(dǎo)出對象都需要注釋說明其用途；非導(dǎo)出對象根據(jù)情況進(jìn)行注釋。

• 如果對象可數(shù)且無明確指定數(shù)量的情況下，一律使用單數(shù)形式和一般進(jìn)行時描述；否則使用復(fù)數(shù)形式。

• 包、函數(shù)、方法和類型的注釋說明都是一個完整的句子。

• 句子類型的注釋首字母均需大寫；短語類型的注釋首字母需小寫。

• 注釋的單行長度不能超過 80 個字符。

• 類型的定義一般都以單數(shù)形式描述：

  //?Request?represents?a?request?to?run?a?command.??type?Request?struct?{?...
  

• 如果為接口，則一般以以下形式描述：

  //?FileInfo?is?the?interface?that?describes?a?file?and?is?returned?by?Stat?and?Lstat.
  type?FileInfo?interface?{?...
  

• 函數(shù)與方法的注釋需以函數(shù)或方法的名稱作為開頭：

  //?Post?returns?*BeegoHttpRequest?with?POST?method.
  

• 如果一句話不足以說明全部問題，則可換行繼續(xù)進(jìn)行更加細(xì)致的描述：

  //?Copy?copies?file?from?source?to?target?path.
  //?It?returns?false?and?error?when?error?occurs?in?underlying?function?calls.
  

• 若函數(shù)或方法為判斷類型（返回值主要為 bool 類型），則以 returns true if 開頭：

  //?HasPrefix?returns?true?if?name?has?any?string?in?given?slice?as?prefix.
  func?HasPrefix(name?string,?prefixes?[]string)?bool?{?...
  

5.3 特別注釋

• TODO：提醒維護(hù)人員此部分代碼待完成

• FIXME：提醒維護(hù)人員此處有BUG待修復(fù)

• NOTE：維護(hù)人員要關(guān)注的一些問題說明

6. 包的導(dǎo)入

單行的包導(dǎo)入

import?"fmt"

多個包導(dǎo)入，請使用 () 來組織

import?(
??"fmt"
??"os"
)

另外根據(jù)包的來源，對排版還有一定的要求

1. 標(biāo)準(zhǔn)庫排最前面，第三方包次之、項(xiàng)目內(nèi)的其它包和當(dāng)前包的子包排最后，每種分類以一空行分隔。

2. 盡量不要使用相對路徑來導(dǎo)入包。

import?(
????"fmt"
????"html/template"
????"net/http"
????"os"

????"github.com/codegangsta/cli"
????"gopkg.in/macaron.v1"

????"github.com/gogits/git"
????"github.com/gogits/gfm"

????"github.com/gogits/gogs/routers"
????"github.com/gogits/gogs/routers/repo"
????"github.com/gogits/gogs/routers/user"
)

7. 善用 gofmt

除了命名規(guī)范外，Go 還有很多格式上的規(guī)范，比如

1. 使用 tab 進(jìn)行縮進(jìn)

2. 一行最長不要超過 80 個字符

因此在格式上的問題，你大部分都可以放心交由 gofmt 幫你調(diào)整。關(guān)于 gofmt 的文章還在寫，應(yīng)該這兩天就會更新。你可以過兩天再來看看。