注释中的函数名称

Question

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'.

Answer 1

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 $