Hacker News Reader

Comment by mwcampbell | Hacker News Reader

> Go has a convention that doc comments must begin with the name of the entity they describe.

Does anyone know the rationale for this one? My only guess is that the other common style, where the doc comment starts with a verb, allows for variation in how that opening verb is conjugated, e.g. "Decompress the tarball" versus "Decompresses the tarball". Maybe the Go team figured they'd eliminate that ambiguity by establishing a convention that the doc comment always starts with a complete sentence with an explicit subject.

View on HN

I think this very specific details is what summarize to me the pain of using go.

Everything is a "convention" but nothing is enforced in a way that would make it easy for developer. There is actually nothing preventing you to not write doc comments like that, nothing to enforce err check, to put interface{} everywhere, to assign nil to a pointer, etc...

By design the language is actually super loose and it heavily contradicts the goal of the language itself. When they say it was for junior/quick onboarding I have nervous laughs, I never saw that much coding mistakes happening to senior devs than in a Go codebase.

You only follow standards if you use golangci which is not even an official tool.

If you think Go is bad, I hope you never have to work on a project with eslint - its default configuration is pure OCD (complains about max line lengths, spacing before/after operators, using "++" etc. etc.), and 90% of the things I find most annoying could be fixed by using gofmt in Go - except of course there is no built-in formatting tool for the JS ecosystem...

> except of course there is no built-in formatting tool for the JS ecosystem

What about prettier? Sure, it's not "built-in", but it's still easy enough to use and enforce within a given project.

I think they refer to the following suggestion:

> 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 every doc comment begins with the name of the item it describes, you can use the doc subcommand of the go tool and run the output 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 [...]

source: https://go.dev/doc/effective_go#commentary

My guess is that it dates back to the beginning when there weren't good documentation search tools? Very simple search tools like "grep" will return useful results if the function name appears in the doc string.

It doesn't seem very important nowadays, though.

It's a weird call-out in the post, especially since their example is a non-exported function.

Ah, making it non-exported was an unintentional mistake. I've pushed a fix marking it as exported with an EDIT note.

For the substantive critique: it's also a bit weird because it's pretty clear what the reason for it is: it's a simplifying convention, like the capital-letters-to-export thing (which I'm partial to, since it's a convention I use in my C code). It seems reasonable to have preferences in the other direction, but (and I'm not trying to argue that you wrote it this way) not to suggest that it's somehow a flaw in the language.

Reply on news.ycombinator.com