根据“有效围棋”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 文档字符串？”，但我确实想确保在学习一门新语言时我坚持使用特定于语言的规范做事方式。
【问题讨论】：
请注意，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的cyclomatic complexity，然后我拆分函数。
此外，更改需要更新 godoc 以及名称
这就是想法：保持文档同步（golint 有帮助）
【讨论】：
以下是编写 doc cmets 的几个原因：
皮棉。如果您使用golint，它将在每个没有文档注释的导出方法上打印警告。如果你有很多这样的东西，你可能会不小心错过一些实际上应该记录在案的东西。在您的代码中使用零个golint 警告可以让您在文档在某处丢失或您有其他样式不一致时快速做出反应。
更改。代码一直在变化。也许现在你的FrontPageView 是一个没有内容的单行，但将来它可能会变得更复杂，所以你无论如何都必须添加一个文档评论来解释发生了什么。
希腊语。在您的示例中，如果我是一名新开发人员并且我的任务与首页有关，我可能会执行godoc pkg | grep 'front page' 或git grep 'front page'。如果您不提供 doc 评论，那么这两个对我来说可能都没用，我将不得不启动 godoc 网络界面以用我的眼睛查找它，或者尝试其他一些 grep。
【讨论】：
golint，并且从现在开始会这样做（感谢您和 VonC 指出这一点），但是关于您对更改的一点看法 - 这是我的理解有效地清洁代码意味着使用描述函数的一个角色的名称来保持函数的简单性；随着它们变得越来越复杂，您将它们分成多个同样简单的功能。此外，更改需要更新 godoc 和名称。