英文:
Function name in comment
问题
为什么Go程序员将函数名作为函数注释的第一个单词？这是一个技术问题，请不要涉及宗教问题。
例如：
// addOptions将选项s添加到opt中
func addOptions(s string, opt interface{}) (string, error) {
....
这难道不违反了SPOT（单一真理点）原则吗？
我之所以问是因为我相信一定有很好的理由。
这是《The GO Programming Language》（Alan A. A. Donovan和Brian W. Kernighan）中的做法。同样，《The C Programming Language》（Dennis M. Ritchie和Brian W. Kernighan）在1988年也是这样做的。如果这么长时间以来都保持这种做法，似乎一定有很好的理由。
SPOT原则是Eric S. Raymond在《The Art of UNIX Programming》中将其归功于Kernighan。
英文:
Why do Go programmers put the name of the function as the first word of the function comment? This is a technical question please not a religious one.
As an example
// addOptions adds options s to opt
func addOptions(s string, opt interface{}) (string, error) {
....
Dose this not violate the SPOT (Single Point Of Truth) principle?
I am asking because I am sure there is a very good reason.
That is how it is done in 'The GO Programming Language' (Alan A. A. Donovan and Brian W. Kernighan). Also it was done like that in 'The C Programming Language' (Dennis M. Ritchie and Brian W. Kernighan) back in 1988. If it has lasted this long it seems there must be a good reason?
The SPOT principle is attributed to Kernighan by Eric S. Raymond in 'The Art of UNIX Programming'.
答案1
得分: 7
TL;DR 它使得使用grep更容易。
引用自https://golang.org/doc/effective_go.html#commentary，由@twotwotwo提到：
> 文档注释最好作为完整的句子，这样可以进行各种自动化展示。第一句应该是以被声明的名称开头的一句总结。
>
> ...
>
> 如果名称总是在注释中开头，godoc的输出可以方便地通过grep运行。想象一下，如果你记不住名称“Compile”，但是正在寻找正则表达式的解析函数，那么你可以运行以下命令：
$ godoc regexp | grep parse
>
> 如果包中的所有文档注释都以“This function...”开头，grep将无法帮助你记住名称。但是因为该包以名称开头，你会看到类似于这样的内容，它会让你想起你正在寻找的单词。
$ godoc regexp | grep parse
Compile解析正则表达式并在成功时返回一个已解析的Regexp
它简化了持有无法解析的全局变量的安全初始化
它简化了持有无法解析的全局变量的安全初始化 $
英文:
TL;DR it makes grepping easier.
Quoting from https://golang.org/doc/effective_go.html#commentary referred to by @twotwotwo:
> Doc comments work best as complete sentences, which allow a wide
> variety of automated presentations. The first sentence should be a
> one-sentence summary that starts with the name being declared.
>
> ...
>
> If the name always begins the comment, the output of godoc can
> usefully be run through grep. Imagine you couldn't remember the name
> "Compile" but were looking for the parsing function for regular
> expressions, so you ran the command,
>
$ godoc regexp | grep parse
>
> If all the doc comments in the package
> began, "This function...", grep wouldn't help you remember the name.
> But because the package starts each doc comment with the name, you'd
> see something like this, which recalls the word you're looking for.
>
$ godoc regexp | grep parse
Compile parses a regular expression and returns, if successful, a Regexp
parsed. It simplifies safe initialization of global variables holding
cannot be parsed. It simplifies safe initialization of global variables $
通过集体智慧和协作来改善编程学习和解决问题的方式。致力于成为全球开发者共同参与的知识库，让每个人都能够通过互相帮助和分享经验来进步。
评论