8

根据“有效围棋” golang.org/doc/effective_go

程序中的每个导出（大写）名称都应该有一个文档注释。

假设我在一个简单的 Web 应用程序上有一个视图处理程序

// Handle the front page of the website
func FrontPageView(w http.ResponseWriter, r *http.Request) {
    controllers.RenderBasicPage(w, "frontPage") 
}

我的问题是：那个 godoc真的有必要吗？也许我现在只是爱上了 Robert Martin 的 Clean Code，但它似乎是一个有效命名的变量，在这种情况下FrontPageView不需要这样的 godoc。这可能是“需要 javadocs 吗？”的衍生/重复。或“是否需要 python 文档字符串？”，但我确实想确保在学习一门新语言时，我坚持使用特定于语言的规范做事方式。

4

2 回答 2

13

请注意，golint会告诉您 FrontPageView() 的文档必须以

// FrontPageView ...

是的，在“ Go Code Review Comments ”中也描述了在所有导出的方法、函数上包含（这里是一个简短的）注释是一种很好的做法。

记录声明的注释应该是完整的句子，即使这看起来有点多余。
这种方法使它们在提取到 godoc 文档时格式良好。

注释应以所描述事物的名称开头，并以句点结尾：

// A Request represents a request to run a command.
type Request struct { ...

// Encode writes the JSON encoding of req to w.
func Encode(w io.Writer, req *Request) { ...

我的理解是，有效地清洁代码意味着使用描述函数的一个角色的名称来保持函数的简单性；

然后文档可以包括边缘情况（即使在你的情况下没有）。
无论如何，添加一个简短的文档不会使它“不那么干净”。

随着它们变得越来越复杂，您将它们分成多个同样简单的功能。

为此，我使用gocyclo：任何高于 10 的圈复杂度，然后拆分函数。

此外，更改将需要更新 godoc 以及名称

这就是想法：保持文档同步（并提供golint帮助）

于 2014-11-17T13:34:25.847 回答
5

以下是编写文档注释的几个原因：

  • 皮棉。如果您使用golint，它将在每个没有文档注释的导出方法上打印警告。如果你有很多这样的东西，你可能会不小心错过一些实际上应该记录在案的东西。在您的代码中零golint警告可以让您在文档在某处丢失或您有其他样式不一致时快速做出反应。

  • 变化。代码一直在变化。也许现在您FrontPageView的内容是单行的，但将来它可能会变得更加复杂，因此无论如何您都必须添加文档注释来解释发生了什么。

  • 格雷普。在您的示例中，如果我是一名新开发人员，并且我的任务与首页有关，我可能会执行godoc pkg | grep 'front page'or git grep 'front page'。如果您不提供 doc 评论，那么这两个对我来说可能都没用，我将不得不启动 godoc web 界面来用我的眼睛寻找它，或者尝试其他一些 grep。

于 2014-11-17T13:35:10.167 回答