Come documentare le funzioni setter autoesplicative? [duplicare]

Question

Come documentare le funzioni setter autoesplicative? [duplicare]

#1 da (4 voti)
#2 da (3 voti)

0

Spesso i setter booleani sono piuttosto auto-esplicativi, come setLogErrors($bool) . Vedo alcuni vantaggi nel fornire alcune informazioni aggiuntive nella documentazione, in questo caso forse dove vengono registrati questi errori. Ma quanta documentazione è troppo, soprattutto quando si tratta di documentare il valore che viene passato al setter? Strumenti di documentazione come phpDocumentor vorrebbero che anche la variabile fosse documentata, ma dal contesto è abbastanza chiaro che richiede un valore booleano. Spesso personalmente lo trovo migliore quando il codice parla da solo, specialmente in situazioni come questa.

Qual è la migliore pratica in situazioni come questa? Se l'argomento è documentato o no, che ne dici di il setter, dovrebbe essere documentato ? La leggibilità del codice non migliorerebbe se ci fosse meno documentazione in questa circostanza? Non faccio parte di un grande team di sviluppo e non leggo molto codice scritto da altri. Speravo di ottenere alcune informazioni su quali standard sono impostati nelle organizzazioni più grandi e quale è il modo più semplice per le persone di leggere quando il codice non è proprio .

Spero che queste domande non siano troppo basate sull'opinione pubblica.

programming-practices documentation

posta DudeOnRock 26.02.2014 - 06:26

fonte

2 risposte

Leggi altre domande sui tag programming-practices documentation

In che modo l'assemblaggio si riferisce al codice macchina / binario Come far funzionare i metodi C # come le funzioni javascript? [chiuso]

score 4 · Answer 1

Per la maggior parte sono d'accordo con te, ma poi mi è venuto in mente un altro punto di vista, che è quando usi un IDE.

Se sto modificando il codice Java usando Eclipse, è molto utile poter passare il mouse su un metodo e vedere JavaDoc. Se il metodo non è stato documentato, diciamo perché è "ovvio", non ho alcuna documentazione. Questo mi fa meravigliare: il programmatore non si è mai preoccupato? Potrebbe fare qualcos'altro, anche se sembra semplice? Considerando che aggiungendo il JavaDoc "ovvio", posso verificare rapidamente che il metodo faccia, in effetti, solo quello che penso (questo si basa sul fatto che JavaDoc sia accurato, ovviamente).

Oltre a ciò, lasciare i metodi non documentati può essere preso da sviluppatori pigri come una scusa per non documentare altri metodi meno ovvi. C'è qualcosa da dire per mantenere i tuoi standard.

score 3 · Answer 2

Le lingue sono diverse a questo riguardo, ma preferisco di gran lunga i singoli attributi, che possono essere documentati in un unico posto. Qualcosa come:

"""Whether errors should be logged or pass silently, True by default"""
log_errors = True

Se devi avere un getter e un setter, i due dovrebbero usare docstring quasi identici. Documenta cosa fa la variabile, non solo che stai impostando una variabile denominata log_errors .