all: document the default doc assumptions around concurrency, zero values, interfaces and return values

[empijei]

In general, across all go libraries, some documentation rules are implicit. As @bradfitz worded it:

The assumption when unstated is that things are not safe for concurrent use, that zero values are not usable, that implementations implement interfaces faithfully, and that only one return values is non-zero and meaningful.

This is a very important piece of knowledge and I think it should be documented somewhere. I don't know if the right place for it would be "Effective Go" (especially considering #28782) but it feels like newcomers should know this before they start browsing Go docs or writing Go code.

[bcmills]

@davecheney's various blog posts and talks are a good resource for these. (I'm sure there are others too, but his come to mind.)

[bcmills]

Note that Effective Go in particular is proposed to be frozen (#28782), so that's probably not a great location. The Tour, the FAQ, or How to Write Go Code all seem like reasonable candidates, though.

[jusmarks]

The assumption when unstated is that things are not safe for concurrent use, that zero values are not usable, that implementations implement interfaces faithfully, and that only one return values is non-zero and meaningful.

Surely at least these two assumptions need to be officially documented?? The last one especially has caused me much endless paranoia and thus needless checking of result values for nil and zero-valued composites, even when I know it's likely not needed; but I do so anyway just for the sake of certainty and therefore my sanity.

In particular I would be tremendously relieved to have it officially documented that a nil error expects a non-nil or non-zero-valued composite result, unless stated otherwise. And vice versa; a non-nil error expects a zero-valued result, unless stated otherwise (though this one is more intuitively obvious, but it would still be nice to see it officially documented).

[ianlancetaylor]

@Justin-Marks Where would be a good place for this documentation? Where is a place that you would see this? Thanks.

[mvdan]

I keep wanting to reference the assumption of "not safe for concurrent use" by default, and every single time it takes me a good ten minutes of looking around to end up here again :)

Now that #61940 is happening, and we're gaining new useful documentation pages like https://go.dev/doc/modules/layout, I imagine it should be easy to find a spot for this new page.

More than happy to volunteer to write a first draft as a CL if a decision can be made on where it could go. Some thoughts:

• I'd prefer to avoid the FAQ, since it's quite lengthy and this new page could gain quite a bit of text.
• Most Go users don't look at the tour after they've been using Go for some time, so that also doesn't feel right.
• https://go.dev/doc/code also feels like an introductory document, whereas "implicit godoc assumptions" feels more like a reference page.
• https://go.dev/doc/comment feels appropriate, perhaps as a new top-level section like "What to assume unless doc comments say otherwise".
• If we think this is more about Go API design than about godoc comments, we could also consider something like /doc/api.

[krisvih32]

Sorry if necroposting is not allowed, I just got into golang developement using https://go.dev/doc/contribute. I will try to fix