golang/go

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

Open

#30.632 aperta il 6 mar 2019

Vedi su GitHub
 (6 commenti) (0 reazioni) (0 assegnatari)Go (19.008 fork)batch import
DocumentationNeedsInvestigationSuggestedhelp wanted

Metriche repository

Star
 (133.883 star)
Metriche merge PR
 (Nessuna PR mergiata in 30 g)

Descrizione

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.

Guida contributor

Direzione di ricerca
Identificare la posizione appropriata nella documentazione di Go (ad esempio Effective Go, FAQ o un nuovo documento) per aggiungere una sezione sulle ipotesi predefinite riguardanti la sicurezza della concorrenza, i valori zero, le implementazioni delle interfacce e i valori di ritorno. Raccogliere il consenso della comunità tramite commenti sul problema.
Tech stack
go
Dominio
documentation
Tipo issue
Documentazione
DifficoltàQuanto dovrebbe essere impegnativa per un nuovo contributor.
2
Tempo stimatoTempo stimato per completare e verificare uno scope piccolo.
1-3 ore
Stato attivitàQuanto è probabile che la issue sia ancora attiva e reviewable.
Datata
ChiarezzaQuanto chiaramente la issue descrive problema, scope e risultato atteso.
Chiara
Prerequisiti
Go
Adatta ai principiantiQuanto la issue è adatta a contributor alla prima esperienza.
65