Go中变量命名规则与实例

前言

来自 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 等包名。

结论

使用短变量名

变量取名考虑上下文，避免冗余，例如函数内的局部变量考虑函数名，包导出变量考虑包名

频道导航