New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
doc: Document the default doc assumptions #30632
Comments
@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.) |
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. |
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). |
@Justin-Marks Where would be a good place for this documentation? Where is a place that you would see this? Thanks. |
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:
|
In general, across all go libraries, some documentation rules are implicit. As @bradfitz worded it:
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.
The text was updated successfully, but these errors were encountered: