常规注释

每种开发语言都有自己的注释语法和格式，也大多类似。 Go 语言和市面上其它多种高级语言的注释语法也类似，主要有以下两种语法格式:

  • 注释行 以符合 // 开头
  • 注释块 以符号 /* 注释内容 */ 包括

但是，以上也就仅仅是正常情况。在很多特殊情况下，一些看似符合以上注释语法的地方，却不是注释，也是本文整理的重点。

“奇怪”的注释

  • 条件编译标签
1
// +build linux,386 darwin,!cgo [条件编译组合结果是： (linux AND 386) OR (darwin AND (NOT cgo))]

在一些特殊的 Go 代码实现文件中，可以看到 // +build 开头的注释，而且此类 Go 代码实现中的函数常常还会在其它类似的文件中出现不同的实现。此类注释，称之为条件编译标签。它有明显的特征，即单独一行或多行，均以// +build开头，同时和其它代码或者注释之间通过空行隔开。

  • 二进制包
1
2
3
//go:binary-only-package

package mypkg

同条件编译标签类似，同样需要与其它代码或者注释之间通过空行隔开。但是注释为固定內容： //go:binary-only-package时（注意没有空格），代表代码中直接引用二进制包。二进制包的位于：$GOPATH/pkg/路徑下。

  • 代码生成

在 Go 项目中，常常会看到很多符合这样的正则表达式的注释内容

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

即表示该 Go 代码文件是通过工具自动化生成的，不可修改。实现 Go 代码文件的自动生成的方法很多，工具也有很多。常见工具有：protoc + protoc-gen-go 组合，以及 stringer 工具等等。

熟悉 go tool 工具中的 generate 的话， 可以直接通过以下注释格式的方式，将生成代码的具体命令操作，写在 Go 代码文件中。例如：

1
//go:generate command argument...

这样在执行 go generate 命令时，该命令会自动检索 Go 代码文件中的注释指令，并依次执行，如有多条指令的话。

  • Cgo代码块
1
2
3
4
5
6
7
8
9
/*
#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开头的注释：

1
2
3
4
5
6
7
8
9
/*
#cgo CFLAGS: -I .
#cgo LDFLAGS: -L . -lclibrary

#include "clibrary.h"

int callOnMeGo_cgo(int in); // Forward declaration.
*/
import "C"

其中，#cgo开头的行作用是指定具体 C 代码的编译链接参数。

  • 官方包中的提示注释[指令]
1
2
3
//go:embed hello.txt
var s string
print(s)

详细文档：https://pkg.go.dev/embed