Question

根据＆＃34; Effective Go＆＃34; 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 真的是必要的吗？也许我现在爱上了罗伯特·马丁的清洁代码，但它似乎是一个有效命名的变量，在这种情况下FrontPageView消除了对这样一个godoc的需要。这可能是＆＃34;衍生/重复是必要的javadoc？＆＃34;或者＆＃34;是否需要python docstrings？＆＃34;，但我确实想确保在学习一门新语言时我会坚持使用语言特定的规范方法。

Answer 1

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

开头

// FrontPageView ...

是的，最好在所有导出的方法和函数中包含（此处为简短的）注释，如＆＃34; Go Code Review Comments＆＃34;中所述。

记录声明的评论应该是完整的句子，即使这看起来有点多余   这种方法使它们在提取到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) { ...

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

然后，文档可以包含边缘情况（即使在您的情况下没有）在任何情况下，添加一个简短的文档都不会使它变得不那么干净＆＃34;。

随着它们变得越来越复杂，你将它们分成多个同样简单的函数。

我使用gocyclo：10以上任何cyclomatic complexity，我将功能分开。

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

这就是主意：保持文档同步（和golint帮助）

Answer 2

撰写文档评论有以下几个原因：

棉绒。如果您使用golint，它将在每个没有文档注释的导出方法上打印警告。如果你有很多那些你可能会意外遗漏应该记录的东西。代码中包含golint个警告，可以让您在某个地方丢失文档时快速做出反应，或者您有其他样式不一致的情况。
变化。代码一直在变化。也许现在你的FrontPageView是一个没有内容的单行，但将来它可能会变得更复杂，所以你不得不添加一个文档评论来解释，发生了什么。
< / LI>
grep的。在您的示例中，如果我是新开发人员并且我已经完成了与首页有关的任务，那么我可能会godoc pkg | grep 'front page'或git grep 'front page'。如果你没有提供doc评论，那么这两个对我来说可能都是无用的，我将不得不用我的眼睛启动godoc web界面来寻找它，或者尝试其他一些greps。

在导出的名字上排除godocs是不好的形式？

2 个答案: