golang/go

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

Open

#30,632 opened on Mar 6, 2019

View on GitHub
 (6 comments) (0 reactions) (0 assignees)Go (19,008 forks)batch import
DocumentationNeedsInvestigationSuggestedhelp wanted

Repository metrics

Stars
 (133,883 stars)
PR merge metrics
 (No merged PRs in 30d)

Description

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.

Contributor guide

Research direction
Identify the appropriate location in the Go documentation (e.g., Effective Go, FAQ, or a new document) to add a section about default assumptions regarding concurrency safety, zero values, interface implementations, and return values. Gather consensus from the community via comments on the issue.
Tech stack
go
Domain
documentation
Issue type
Documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
Go
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
65