9.4 Go语言命名编码规范

每个语言都有自己特色的命名规范,学习该语言的命名规范,能让你写出来的代码更加易读。

以下内容整理自:Go语言(Golang)编码规范

命名规范分为以下几点

1. 文件命名

文件名应一律使用小写(因为Windows的原因), 不同单词之间用下划线分割。

应用的主入口应当为 main.go ,或者为应用名的全小写形式,比如 Gogs 的入口应当为 gogs.go

2. 常量命名

  • 常量均需使用全部大写字母组成,并使用下划线分词:

    const APP_VER = "0.7.0.1110 Beta"
    
  • 如果是枚举类型的常量,需要先创建相应类型:

    type Scheme string
    const (
        HTTP  Scheme = "http"
        HTTPS Scheme = "https"
    )
    
  • 如果模块的功能较为复杂、常量名称容易混淆的情况下,为了更好地区分枚举类型,可以使用完整的前缀:

    type PullRequestStatus int
    const (
        PULL_REQUEST_STATUS_CONFLICT PullRequestStatus = iota
        PULL_REQUEST_STATUS_CHECKING
        PULL_REQUEST_STATUS_MERGEABLE
    )
    

3. 变量命名

使用驼峰命名法

  • 在相对简单的环境(对象数量少、针对性强)中,可以将完整单词简写为单个字母,例如:user写为u

  • 若该变量为 bool 类型,则名称应以 Has, Is, CanAllow 开头。例如:isExist ,hasConflict 。

  • 其他一般情况下首单词全小写,其后各单词首字母大写。例如:numShips 和 startDate 。

  • 若变量中有特有名词(以下列出),且变量为私有,则首单司还是使用全小写,如 apiClient

  • 若变量中有特有名词(以下列出),那首单词就要变成全大写。例如:APIClient

下面列举了一些常见的特有名词:

// 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,
}

接口命名

使用驼峰命名法,可以用 type alias 来定义大写开头的type 给包外访问。

type helloWorld interface {
    func Hello();
}

type SayHello helloWorld

注释规范

单行注释使用 // ,多行注释使用 /* comment */

// go语言

/*
Go 语言
Hello, World
*/
  • 所有导出对象都需要注释说明其用途;非导出对象根据情况进行注释。

  • 如果对象可数且无明确指定数量的情况下,一律使用单数形式和一般进行时描述;否则使用复数形式。

  • 包、函数、方法和类型的注释说明都是一个完整的句子。

  • 句子类型的注释首字母均需大写;短语类型的注释首字母需小写。

  • 注释的单行长度不能超过 80 个字符。

  • 包级别的注释说明,只需要在一个源文件中注释即可,并且放在 package 之前

  • 如果是特别复杂的包,可单独创建 doc.go 文件说明

  • 类型的定义一般都以单数形式描述:

    // 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 { ...
    
  • 函数与方法的注释需以函数或方法的名称作为开头:

    // Post returns *BeegoHttpRequest with POST method.
    
  • 如果一句话不足以说明全部问题,则可换行继续进行更加细致的描述:

    // Copy copies file from source to target path.
    // It returns false and error when error occurs in underlying function calls.
    
  • 若函数或方法为判断类型(返回值主要为 bool 类型),则以 <name> returns true if 开头:

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

特别注释

  • TODE:提醒维护人员此部分代码待完成

  • FIXME:提醒维护人员此处有BUG待修复

  • NOTE:维护人员要关注的一些问题说明