前言

來自 Google 的 Andrew Gerrand 曾經關于 Go 中的參數命名規范進行了分享，slides 為 https://talks.golang.org/2014/names.slide

命名習慣很重要

• 良好的可讀性是高質量代碼的要求之一
• 良好的命名習慣有助于提高代碼可讀性

良好命名喜歡的特質

Good Name 將具有如下的特質：

• Consistent (easy to guess),
• Short (easy to type),
• Accurate (easy to understand)

經驗法則

變量申明與變量使用之間越遠，那么變量名字應當越長。

這也解釋了，為什么 for 循環次數變量使用 i 作為遍歷用的臨時變量，而不是語義上更具體的 index 作為變量名。

大小寫混用的變量名

我們不應該使用 names_with_underscores 作為變量名，而是 namesWithUnderscores 作為變量名。

另一方面，首字母縮略詞，應當是大寫，例如 ServeHTTP 以及 IDProcessor。

這被稱為 MixedCase，類似于駝峰原則命名，但是專業詞匯的首字母縮寫均應當寫成大寫形式。

變量名避免冗余

變量名不是越長越好，常變量名會模糊代碼功能。

常見的常量、類型組合可能使用非常簡短的名字：

• 使用 i 而不是 index
• 使用 r 而不是 reader
• 使用 b 而不是 buffer

根據上下文，避免使用冗余的名稱：

• 在 RuneCount 方法內部，使用 count 而不是 reuneCount
• 在 map 語句中，使用 ok 而不是 keyInMap：

v, ok := m[k]

常變量名也許在長函數、有很多變量的函數中有幫助，但是這通常也意味著你應該重構代碼。

Bad codes vs good codes

// Bad
func RuneCount(buffer []byte) int {
      // runeCount -> count
    runeCount := 0
      // index -> i , buffer -> b
    for index := 0; index < len(buffer); {
        if buffer[index] < RuneSelf {
            index++
        } else {
              // size -> n
            _, size := DecodeRune(buffer[index:])
            index += size
        }
        runeCount++
    }
    return runeCount
}

// Good
func RuneCount(b []byte) int {
    count := 0
    for i := 0; i < len(b); {
        if b[i] < RuneSelf {
            i++
        } else {
            _, n := DecodeRune(b[i:])
            i += n
        }
        count++
    }
    return count
}

函數參數的命名

函數參數與變量名一樣，都起到了文檔的作用。

1.當函數參數的類型具有描述性時，那么函數參數名就可以簡短一些：

func AfterFunc(d Duration, f func()) *Timer
func Escape(w io.Writer, s []byte)

2.當函數參數的類型語義不清，那么參數名應當更具體詳細一些：

func Unix(sec, nsec int64) Time
???????func HasPrefix(s, prefix []byte) bool

返回值的命名

導出函數（exported function）返回值應當僅僅出于編寫文檔目的進行命名。

下面是返回值命名的好例子：

// Good
func Copy(dst Writer, src Reader) (written int64, err error)
// Good
func ScanBytes(data []byte, atEOF bool) (advance int, token []byte, err error)

方法 Receiver 的命名

Go 中結構體可以擁有方法，在為結構體聲明方法時，結構體被稱為 receiver。

按照慣例，方法接收者的命名通常為 1 個字符或者 2 個字符，因為結構體的每一個方法都將使用同一個 receiver 名稱。

// Good
func (b *Buffer) Read(p []byte) (n int, err error)
// Good
func (sh serverHandler) ServeHTTP(rw ResponseWriter, req *Request)
// Good
func (r Rectangle) Size() Point

Receiver 的名稱一定要確保一致性，如果結構體的 method1 使用 r 作為 receiver 名稱，那么 method2 就不應當使用 rdr 作為名稱。

導出 package 級別變量命名

package 級別的變量已經被 package name 限定了，因此需要注意導出變量、常量、函數、類型名的冗余問題。

例如：

• 我們使用 bytes.Buffer 而不是 bytes.ByteBuffer
• 我們使用 strings.Reader 而不是 strings.StringReader

導出變量名不要與 package 之間存在冗余。

接口類型

只有一個方法的接口，接口名通常簡單在方法后面加上 er 來進行命令，例如：

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

有時候，上述策略會導致接口名語法不正確，但是我們仍然可以選擇這么做，例如：

type Execer interface {
    Exec(query string, args []Value) (Result, error)
}

也有時候，我們會修改接口名，使得其符合英語語法：

type ByteReader interface {
    ReadByte() (c byte, err error)
}

當一個接口包含多個方法時，應當選擇一個準確描述其用途的名稱，例如 net.Conn，http.ResponseWriter，io.ReadWriter。

error 命名

錯誤類型與錯誤變量應當有不同的命名格式：

// 錯誤類型 Error types
type ExitError struct {
    ...
}

// 錯誤變量 Error values
var ErrFormat = errors.New("image: unknown format")

Packages 名

選擇對導出的名稱具有意義的包名稱。

避免使用 util、common 等包名。

結論

使用短變量名

變量取名考慮上下文，避免冗余，例如函數內的局部變量考慮函數名，包導出變量考慮包名

總結