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

Question

根据"Effective Go" golang.org/doc/effective_go

程序中的每个导出(大写)名称都应具有doc注释.

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

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

我的问题是:godoc 真的有必要吗？也许我现在爱上了罗伯特·马丁的清洁代码,但它似乎是一个有效命名的变量,在这种情况下,FrontPageView不再需要这样一个godoc.这可能是"必要的javadoc"的衍生/重复吗？或者"python docstrings是否必要？",但我确实想确保在学习一门新语言时我会坚持使用语言特定的规范方法.

Answer 1

请注意,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) { ... 

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

然后,doc可以包含边缘情况(即使在您的情况下没有).
无论如何,添加一个简短的文档不会使它"不那么干净".

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

我使用gocyclo:任何超过10的圈复杂度,我分裂函数.

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

这就是想法:保持文档同步(和golint帮助)

Answer 2

以下是撰写文档评论的几个原因:

• 皮棉.如果使用golint,它将在没有doc注释的每个导出方法上打印警告.如果你有很多那些你可能会意外遗漏应该记录的东西.在golint代码中没有警告可以让您在某个地方丢失文档时快速做出反应,或者您有其他样式不一致.

• 变化.代码一直在变化.也许现在你FrontPageView的单行内容没有内容,但将来它可能会变得更复杂,所以你不得不添加一个文档评论来解释,发生了什么.

• grep的.在你的例子中,如果我是一个新的开发人员并且我有一个与头版有关的任务,我可能会做godoc pkg | grep 'front page'或git grep 'front page'.如果你没有提供doc评论,那么这两个对我来说可能都是无用的,我将不得不启动godoc web界面来用我的眼睛来寻找它,或者尝试其他一些greps.