在导出的名称上排除godoc是否不好？

根据“有效围棋”

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

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

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

我的问题是：godoc真的有必要吗？也许我现在只是喜欢Robert Martin的干净代码，但它似乎是一个有效命名的变量，在本例中，FrontPageView不再需要这样的godoc。这可能是“javadocs必要吗？”或“python docstrings必要吗？”的派生/复制，但我确实希望确保在学习一门新语言时，我坚持使用特定于语言的规范方法来做事情

注意，这会告诉您FrontPageView（）的文档必须以开头

// FrontPageView ...

是的，这是一个很好的做法，包括（这里是一个简短的）对所有导出的方法和函数的注释，如“”中所述

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

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

---

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

然后，文档可以包括边缘案例（即使在您的案例中没有） 在任何情况下，添加一个短文档都不会使其“不干净”

随着它们变得越来越复杂，您可以将它们拆分为多个同样简单的函数

我用这个：任何超过10，我分裂的功能

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

---

这就是想法：保持文档同步（并且

golint

有帮助）

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

• 皮棉。如果使用

  golint

  ，它将在没有文档注释的每个导出方法上打印警告。如果你有很多这样的东西，你可能会意外地错过一些应该记录下来的东西。如果代码中没有

  golint

  警告，则当文档丢失或存在其他样式不一致时，您可以快速做出反应

• 变化。代码一直在变化。也许现在你的

  FrontPageView

  只是一行，没有内容，但将来它可能会变得更复杂，因此你必须添加一条文档注释来解释发生了什么

• 格雷普。在您的示例中，如果我是一名新开发人员，并且我被分配了一项与首页相关的任务，我可能会执行

  godoc pkg | grep“首页”

  或

  git grep“首页”

  。如果你不提供文档注释，这两种注释对我来说可能都没用，我要么启动godoc web界面用眼睛查找，要么尝试其他一些grep

---

是的，所以我没有使用过

golint

，从现在起我将这样做（感谢您和VonC指出这一点），但是关于您的更改-我的理解是，有效地清理代码意味着使用描述函数的一个角色的名称保持函数的简单；随着它们变得越来越复杂，您可以将它们拆分为多个同样简单的函数。此外，更改还需要更新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) { ...