Scrivere documentazione

[mircov]

Salve. Quando si scaricano programmi tipo un CMS vedendo il codice dei file si possono notare moltissimi commenti.
Questi commenti, però, hanno una struttura molto articolata.

Ora mi chiedevo: si seguono delle linee guida quando si scriono o quando si scrive la documentazione oppure ognuno scrive nel modo che vuole?

La domanda me la sono posta maggiormente quando ho letto su una guida che l'autore aveva scritto anche un'altra guida che parlava proprio di come scrivere la documentazione. Purtroppo non c'era il link e non sono riuscito a trovarne un altra. Mi potreste dare delle indicazioni? (Se ce n'è bisogno ovviamente!)

Grazie mille! Ciao!

[M4rko]

Per le classi ci sono alcuni strumenti che consentono di standardizzare il formato dei commenti e di generare in automatico la documentazione partendo da questi, sia in formato html che in altri formati (pdf per esempio)

Cerca con google: phpdocumentor, phpdoc, phpdocu
Potrebbe essere un buon punto di partenza.

Per il resto dipende anche dal codice che stai scrivendo, diciamo che non si deve esagerare in nessuna direzione (ne pochi commenti, ne troppi).
Sicuramente, immaginando di avere un file che gestisce un modulo dell'applicazione, ci andrebbe un'intestazione che fornisce varie informazioni tra cui la licenza, l'ultima modifica, cosa fa e cosa non fa quel modulo (in maniera sintetica), cosa bisogna ancora aggiungere o correggere (tipo "todo list" oppure "fixme!", cose del genere)

Per il resto basta un po di buon senso. Immagina di essere uno sviluppatore che si trova a dover maneggiare il tuo codice: quali commenti vorresti trovarci? e quali riterresti superflui?

[mircov]

Ok, grazie per la risposta! ciao!