Go 編程： 那些奇怪的註釋

自從上篇總結了一下Go 編程： 交叉編譯 vs 條件編譯以後，以爲有必要對於相似條件編譯標籤等特殊註釋作一次簡單收集。

原文發佈於我的站點: GitDiG.com, 原文連接: Go 編程： 那些奇怪的註釋

1. 常規註釋

每種開發語言都有本身的註釋語法和格式，也大多相似。 Go 語言和市面上其它多種高級語言的註釋語法也相似，主要有如下兩種語法格式:

• 註釋行 以符合 // 開頭
• 註釋塊 以符號 /* 註釋內容 */ 包括

一般狀況下， 對外公開的包、函數、常量、變量均須要進行註釋。代碼是否註釋徹底，能夠經過lint工具進行審查。不瞭解的話，能夠參考像 Awesome-Go 同樣提高企業 Go 項目代碼質量一文。

可是，以上也就僅僅是正常狀況。在不少特殊狀況下，一些看似符合以上註釋語法的地方，卻不是註釋，也是本文整理的重點。

2. 「奇怪」的註釋

2.1 條件編譯

在一些特殊的 Go 代碼實現文件中，能夠看到 // +build 開頭的註釋，並且此類 Go 代碼實現中的函數經常還會在其它相似的文件中出現不一樣的實現。此類註釋，稱之爲條件編譯標籤。它有明顯的特徵，即單獨一行或多行，均以// +build 開頭，同時和其它代碼或者註釋之間經過空行隔開。

例如：

// +build linux,386 darwin,!cgo
複製代碼

條件編譯組合結果是： (linux AND 386) OR (darwin AND (NOT cgo))

// +build linux darwin
// +build 386
複製代碼

條件編譯組合結果是：(linux OR darwin) AND 386

具體詳細的條件編譯的內容參考: Go 編程： 交叉編譯 vs 條件編譯.

2.2 二進制包

同條件編譯標籤相似，一樣須要與其它代碼或者註釋之間經過空行隔開。可是註釋爲固定內容： //go:binary-only-package時，表明代碼中直接引用二進制包。二進制包的位於：$GOPATH/pkg/路徑下。

//go:binary-only-package

package mypkg
複製代碼

代碼中直接引用二進制包， 很是適用於一些敏感或者有必定壁壘的企業核心包的發佈。

2.3 代碼生成

在 Go 項目中，經常會看到不少符合這樣的正則表達式的註釋內容

^// Code generated .* DO NOT EDIT\.$

即表示該 Go 代碼文件是經過工具自動化生成的，不可修改。實現 Go 代碼文件的自動生成的方法不少，工具也有不少。常見工具備：protoc + protoc-gen-go 組合，以及 stringer工具等等。

熟悉 go tool 工具中的 generate 的話， 能夠直接經過如下注釋格式的方式，將生成代碼的具體命令操做，寫在 Go 代碼文件中。例如：

//go:generate command argument...
複製代碼

這樣在執行 go generate 命令時，該命令會自動檢索 Go 代碼文件中的註釋指令，並依次執行，若有多條指令的話。

2.4 Cgo代碼塊

若是在 Go 代碼文件中，看到相似如下的註釋：

/* #include <stdio.h> #include <stdlib.h> void myprint(char* s) { printf("%s\n", s); } */
import "C"
複製代碼

即，一個註釋塊中的內容是 C 代碼，同時，註釋塊結束後，立刻是import "C"則表明該 Go 代碼中引用 C 代碼，其中註釋塊中的內容就是具體的 C 代碼。 C 代碼能夠是簡單頭文件引用，也能夠是具體的實現代碼。

其中，在 Cgo 的代碼塊中，與純 C 代碼稍微不一樣的是， Cgo 代碼中還能夠加入#cgo開頭的註釋：

/* #cgo CFLAGS: -I . #cgo LDFLAGS: -L . -lclibrary #include "clibrary.h" int callOnMeGo_cgo(int in); // Forward declaration. */
import "C"
複製代碼

其中，#cgo開頭的行做用是指定具體 C 代碼的編譯連接參數。

3. 小結

以上就是我想到的一些奇怪的註釋，若有遺漏，歡迎補充。

參考資源：

• Comments
• Cgo