22. 一文了解 Go語言中編碼規範

時間 2020-05-26

原文原文鏈接

Hi，你們好，我是明哥。html

在本身學習 Golang 的這段時間裏，我寫了詳細的學習筆記放在個人我的微信公衆號《Go編程時光》，對於 Go 語言，我也算是個初學者，所以寫的東西應該會比較適合剛接觸的同窗，若是你也是剛學習 Go 語言，不防關注一下，一塊兒學習，一塊兒成長。linux

個人在線博客：golang.iswbm.com 個人 Github：github.com/iswbm/GolangCodingTimeandroid

每一個語言都有本身特點的編碼規範，學習該語言的命名規範，能讓你寫出來的代碼更加易讀，更加不容易出現一些低級錯誤。git

本文根據我的編碼習慣以及網絡上的一些文章，整理了一些你們能用上的編碼規範，多是一些主流方案，但不表明官方，這一點先聲明一下。github

1. 文件命名

因爲 Windows平臺文件名不區分大小寫，因此文件名應一概使用小寫
不一樣單詞之間用下劃線分詞，不要使用駝峯式命名
若是是測試文件，能夠以 _test.go 結尾
文件若具備平臺特性，應以 文件名_平臺.go 命名，好比 utils_ windows.go，utils_linux.go，可用的平臺有：windows, unix, posix, plan9, darwin, bsd, linux, freebsd, nacl, netbsd, openbsd, solaris, dragonfly, bsd, notbsd， android，stubs
通常狀況下應用的主入口應爲 main.go，或者以應用的全小寫形式命名。好比MyBlog 的入口能夠爲 myblog.go

2. 常量命名

目前在網絡上能夠看到主要有兩種風格的寫法golang

第一種是駝峯命名法，好比 appVersion
第二種使用全大寫且用下劃線分詞，好比 APP_VERSION

這兩種風格，沒有孰好孰弱，可自由選取，我我的更傾向於使用第二種，主要是能一眼與變量區分開來。編程

若是要定義多個變量，請使用括號來組織。windows

const (
    APP_VERSION = "0.1.0"
  CONF_PATH = "/etc/xx.conf"
)複製代碼

3. 變量命名

和常量不一樣，變量的命名，開發者們的喜愛就比較一致了，統一使用 駝峯命名法api

在相對簡單的環境（對象數量少、針對性強）中，能夠將完整單詞簡寫爲單個字母，例如：user寫爲u數組
若該變量爲 bool 類型，則名稱應以 Has, Is, Can 或 Allow 開頭。例如：isExist ，hasConflict 。
其餘通常狀況下首單詞全小寫，其後各單詞首字母大寫。例如：numShips 和 startDate 。
若變量中有特有名詞（如下列出），且變量爲私有，則首單詞仍是使用全小寫，如 apiClient。
若變量中有特有名詞（如下列出），但變量不是私有，那首單詞就要變成全大寫。例如：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. 函數命名

函數名仍是使用駝峯命名法
可是有一點須要注意，在 Golang 中是用大小寫來控制函數的可見性，所以當你須要在包外訪問，請使用大寫字母開頭
當你不須要在包外訪問，請使用小寫字母開頭

另外，函數內部的參數的排列順序也有幾點原則

參數的重要程度越高，應排在越前面
簡單的類型應優先複雜類型
儘量將同種類型的參數放在相鄰位置，則只需寫一次類型

5. 接口命名

使用駝峯命名法，能夠用 type alias 來定義大寫開頭的 type 給包外訪問。

type helloWorld interface {
    func Hello();
}

type SayHello helloWorld複製代碼

當你的接口只有一個函數時，接口名一般會以 er 爲後綴

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

5. 註釋規範

註釋分爲

5.1 包註釋

位於 package 以前，若是一個包有多個文件，只須要在一個文件中編寫便可
若是你想在每一個文件中的頭部加上註釋，須要在版權註釋和 Package前面加一個空行，不然版權註釋會做爲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複製代碼

若是是特別複雜的包，可單首創建 doc.go 文件說明

5.2 代碼註釋

用於解釋代碼邏輯，能夠有兩種寫法

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

// 單行註釋

/*
多
行
注
釋
*/複製代碼

另外，對於代碼註釋還有一些更加苛刻的要求，這個看我的了，摘自網絡：

全部導出對象都須要註釋說明其用途；非導出對象根據狀況進行註釋。
若是對象可數且無明確指定數量的狀況下，一概使用單數形式和通常進行時描述；不然使用複數形式。
包、函數、方法和類型的註釋說明都是一個完整的句子。
句子類型的註釋首字母均需大寫；短語類型的註釋首字母需小寫。
註釋的單行長度不能超過 80 個字符。

類型的定義通常都以單數形式描述：

// 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 { ...複製代碼

5.3 特別註釋

TODO：提醒維護人員此部分代碼待完成
FIXME：提醒維護人員此處有BUG待修復
NOTE：維護人員要關注的一些問題說明

6. 包的導入

單行的包導入

import "fmt"複製代碼

多個包導入，請使用 {} 來組織

import {
  "fmt"
  "os"
}複製代碼

另外根據包的來源，對排版還有必定的要求

標準庫排最前面，第三方包次之、項目內的其它包和當前包的子包排最後，每種分類以一空行分隔。
儘可能不要使用相對路徑來導入包。

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"
)複製代碼