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