È una cattiva forma escludere godocs sui nomi esportati?

Question

Secondo "efficace Go" golang.org/doc/effective_go

Ogni esportato (in maiuscolo) nome in un programma dovrebbe avere un commento doc.

Diciamo che ho un gestore di vista su una semplice applicazione web

// Handle the front page of the website 
func FrontPageView(w http.ResponseWriter, r *http.Request) { 
    controllers.RenderBasicPage(w, "frontPage") 
} 

mia domanda è questa: è che GODOC davvero necessario? Forse sono solo innamorato del Codice pulito di Robert Martin in questo momento, ma sembra una variabile con un nome efficace, in questo caso FrontPageView rimuove il bisogno di un simile godoc. Questo è probabilmente un derivato/duplicato di "javadoc sono necessari?" o "sono necessarie le istruzioni di Python?", ma voglio essere sicuro che quando apprendo una nuova lingua mi stia attenendo ai canonici modi di fare delle cose.

Answer 1

Nota che golint vi direbbe che il doc per FrontPageView() deve iniziare con

// FrontPageView ... 

E sì, è buona pratica includere (qui una breve) commento su tutti i metodi esportati, le funzioni, come descritto anche in "Go Code Review Comments".

commenti documentano le dichiarazioni dovrebbero essere frasi complete, anche se questo sembra un po 'ridondante.
Questo approccio li rende formattati correttamente quando vengono estratti in documentazione Godoc.

Commenti dovrebbero iniziare con il nome della cosa essere descritti e fine a un periodo di:

// A Request represents a request to run a command. 
type Request struct { ... 

// Encode writes the JSON encoding of req to w. 
func Encode(w io.Writer, req *Request) { ... 

---

è la mia comprensione che il codice in modo efficace pulita significa mantenere semplici funzioni con un nome che descrive l'unico ruolo della funzione;

Quindi il documento può includere casi limite (anche se nel tuo caso non ce ne sono).
In ogni caso, l'aggiunta di un breve documento non lo renderà "meno pulito".

man mano che diventano più complessi, li dividi in più funzioni ugualmente semplici.

Io uso gocyclo per questo: qualsiasi cyclomatic complexity sopra 10, e dividere la funzione.

Inoltre, i cambiamenti richiederebbero un aggiornamento nel GODOC così come il nome

Questa è l'idea: mantenendo il doc in sincronia (e golint aiuta)

Answer 2

Qui è una coppia dei motivi per scrivere i commenti del doc:

• Lint. Se si utilizza golint, stamperà avvisi su ogni metodo esportato che non ha alcun commento del doc. Se ne hai molti puoi per caso perdere qualcosa che dovrebbe essere effettivamente documentato. Avere zero avvisi golint nel codice ti consente di reagire rapidamente quando i documenti mancano da qualche parte o hai altre incoerenze di stile.

• Modifiche. Il codice cambia continuamente. Forse ora il tuo FrontPageView è un one-liner senza contenuto, ma in futuro potrebbe diventare più complesso, quindi dovrai comunque aggiungere un commento al doc per spiegare cosa sta succedendo.

• Grep. Nel tuo esempio, se sono un nuovo sviluppatore e mi viene assegnato un compito relativo alla prima pagina, probabilmente eseguirò godoc pkg | grep 'front page' o git grep 'front page'. Se non fornisci un commento, entrambi saranno probabilmente inutili per me, e dovrò lanciare l'interfaccia web Godoc per cercarlo con i miei occhi, o provare qualche altro greps.