Skip to content
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

Open
empijei opened this issue Mar 6, 2019 · 2 comments

Comments

@empijei
Copy link
Contributor

commented Mar 6, 2019

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

This comment has been minimized.

Copy link
Member

commented Apr 12, 2019

@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

This comment has been minimized.

Copy link
Member

commented Apr 12, 2019

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
4 participants
You can’t perform that action at this time.