Stile di documentazione [chiuso]

Question

Sono uno sviluppatore web di PHP, che sta cercando un metodo ben collaudato per scrivere una buona documentazione (aka docblock).

Esistono diversi stili di documentazione, ad esempio:

• Il descrittivo ma non classificato (# 1):

/**
 *  Element name: class, function, variable etc. (Optional)
 *  
 *  Short description.
 *
 *  Long description.
 */

• Il classificato (# 2):

/**
 *  Function name
 *
 *  @param $foo
 *  @return bar
 */

• Il modello simile (n. 3):

/**
 **********************
 * NAME:    Func_Name
 * DESC:    Does A Lot
 * RETurn:  number
 * NOTES: foo bar foo...
 **********************
 */

• Variazioni dei metodi sopra menzionati.

Ma quale stile di documentazione devo adottare?

Suppongo che diversi stili di documentazione debbano essere usati per diversi elementi del linguaggio:
Le funzioni forse dovrebbero usare il metodo n. 2,
mentre una classe dovrebbe usare il metodo n. 1.

Un codice inline può essere documentato in questo modo (# 5):

// short description
// of
// what the following code does.

Conosco phpDocumentor, ma non mi piace l'idea di imparare a usarlo.
Sembra ridicolo imparare a usare qualcosa come phpDocumentor solo per poter documentare il mio codice.
(anche se apprezzo qualsiasi progetto open source, incluso phpDocumentor)

Answer 1

Altri probabilmente ti diranno cose più specifiche su PHP.

Tuttavia, direi che la cosa più importante da capire è "chi leggerà questo e quando". Se stai scrivendo alcune importanti API che ti aspetti che molte persone usino e leggano, devi offrire una specifica completa. Un bel stile formale che mostra chiaramente quali sono i parametri, quali sono i valori di ritorno, ecc., Può essere quasi obbligatorio.

Se non stai scrivendo un'API di livello mondiale ma piuttosto un codice interno, pensa ai tuoi lettori. La maggior parte delle persone che leggeranno questo scriverà nel codice. Avranno un'istanza di una classe o chiameranno un metodo per realizzare qualcosa, e non gliene importerebbero due centesimi di tutto ciò che probabilmente possono capire da soli. Riceverai solo un secondo o due di attenzione mentre scremano e devi sfruttare al meglio questo.

In questi casi, una descrizione completa, un elenco completo dei parametri e così via saranno solo "rumore visivo". Se in realtà scrivi qualcosa di sorprendente, unico o importante, forse ti manca. quindi stai meglio optando per documentare ciò che è unico e non documentare altrimenti. La presenza di documentazione sarebbe quindi indicativa per il tuo lettore che in realtà vuole leggere, piuttosto che notare cose che si aspettano diversamente.

Oltre a ciò, direi che dovresti sempre progettare attentamente la tua classe e soprattutto la tua funzione in modo che nessuno abbia bisogno di leggere la documentazione. Se qualcuno ha bisogno di leggere "la breve descrizione" per sapere cosa fa la tua funzione o cosa serve, hai fatto un brutto lavoro nel nominarla o nel distinguerla dagli altri. La documentazione dovrebbe essere l'ultima risorsa, per comunicare cose che non c'è proprio modo di rendere evidente nella firma.