Go 中语义注释有什么用？

Question

通过与这个关于标签的问题进行类比，我注意到评论的多种用途超出了纯粹的评论。

例子：

• go:generate可用于代码生成。
• godoc使用函数名称来指示它应该解释的注释
• 构建约束

还有其他我错过的吗？

有没有明确的清单？

一些第三方软件包（例如gocontracts和go-swagger）也使用它们。他们怎样才能避免彼此冲突呢？

Answer 1

如前所述，注释是 go 中的指令，而不仅仅是注释。

在撰写本文时，还没有明确的清单。这被记录为golang 问题 28532。

因此我建议用这个答案来做一个。

在 go 核心语言和工具本身中的用途：

• go:generate可用于代码生成。
• godoc使用函数名称来指示它应该解释的注释
• 示例- 记录测试的预期输出（感谢@Butuzov）
• 构建约束（以“ // +build ”开头）
• 导入注释，例如' package math // import“path” '

在第三方软件包中的显着用途

• gocontracts - 将前提条件指定为注释
• go-swagger - 使用 swagger 记录 ReST API
• golangci例如 //nolint[:linter1,linter2,...]

他们怎样才能避免彼此冲突呢？

如果您正在开发一个确实需要将注释视为属性的工具，并且希望避免与其他类似用途发生冲突，请在您的注释前添加诸如“ { mytool} : ”之类的名称空间

在命名空间方面有一些有意识的尝试。go 中内置的魔法注释使用“go:”前缀，如“go:generate”（除非不使用）

go-swagger 使用“swagger:”

但是，您仍然需要谨慎对待这个问题，并检查此处的列表或您可以找到的任何其他来源。

还要考虑注释是否是最好的或唯一的方法，而不是使用函数。例如比较（gocontracts）：

// SomeFunc ensures:
//  * !strings.HasSuffix(result, "smth")
func SomeFunc(x int) (result string) {
    // ...
}

与 ( godbc )

func SomeFunc(x int) (result string) {
    godbc.Require(strings.HasSuffix(result,"smth");
}