La verbosità di PHPDoc è più un problema di quanto valga la pena? [chiuso]

Question

Ho provato ad usare PHPDoc per la prima volta oggi e ho riscontrato rapidamente un problema.

Per ogni 1 riga di dichiarazioni variabili, avevo almeno 5 righe di commenti. Esempio:

/**
 * Holds path the remote server
 * @name ...
 * @global ...
 */
 $myvar = ...

Naturalmente, i payoff sono buoni, ma questo trasforma un file di configurazione a 10 righe in un file a 60 righe. Mi ci vuole un'eternità per compilare, e non sono ancora convinto che aggiunga molto più di un semplice one-liner.

Inoltre, crea un nodo nel mio flusso di lavoro. Va tutto bene fino a quando non ho bisogno di fare cambiamenti radicali. Con i miei blocchi di documenti ben documentati, all'improvviso non devo più riformattare il mio codice, ma devo riscrivere tutti questi noiosi dettagli. Aspetta fino alla fine che dici? HAH! Quindi la documentazione non accadrà mai.

Inoltre, mi costringe a scrivere in stile C / ** / commenti nel mezzo del mio codice. Questo mi fa impazzire durante lo sviluppo poiché toglie la possibilità di commentare blocchi di grandi dimensioni su richiesta. Ora per commentare un grosso blocco di codice, devo estrarre qualcosa del tipo: range, s / ^ / # /; quindi annullalo più tardi. Fastidioso!

Per farla breve - Mi piace PHPDoc, adoro il codice ben documentato - ma 5 righe di commenti per ogni riga di codice sono troppo! . Ci sono delle funzioni che mi mancano? È un problema comune?

Answer 1

Il fatto che sia eccessivo dipende in gran parte dall'uso previsto dell'applicazione. Se stai scrivendo un'app che verrà utilizzata solo da una singola società o gruppo, probabilmente non avrai bisogno di una documentazione esaustiva di ogni singola variabile.

Ad esempio, in questo momento sto lavorando a un progetto con una base di codice abbastanza estesa ma pochissimi sviluppatori (per ora, solo io). Sto aggiungendo blocchi PHPDoc per due cose: classi e metodi. Per tutto il resto, commento spesso, ma non in formato PHPDoc dettagliato. La maggior parte di questo codice sarà mai vista da tre o quattro persone e le informazioni di cui avranno bisogno sono informazioni sulla scatola nera: cosa devo inviare a questo metodo, cosa mi aspetto di uscirne. Vogliono sapere come ottenere dati da un Modello, non a cosa serve una variabile di classe privata.

Se stavo scrivendo un'app che intendevo distribuire ad altri sviluppatori o aziende, e mi aspettavo che integrassero la mia app con altri sistemi o ne estendessero le funzionalità, darei più valore all'uso più ampio di PHPDoc. Questo tipo di dettagli potrebbe sicuramente tornare utile durante la manutenzione a lungo termine.

Caso in questione, il mio progetto attuale richiederà ad un certo punto la creazione di un'API per accedere da altri siti. Puoi scommettere che l'API avrà più commenti e documentazione scritta rispetto alle righe di codice.