Documentare il codice Javascript (e non solo…)
Mercoledì 12 Novembre 2008 - 13:08
di Cesare Lamanna
Lunedì scorso abbiamo pubblicato nella sezione Javascript di HTML.it un corposo articolo di Alberto Bottarini: JsDoc Toolkit: documentazione professionale per JavaScript.
Si tratta, come è facile intuire, di una guida all’uso di JsDoc Toolkit, un potente strumento per documentare in modo professionale sorgenti JavaScript.
Cito qui un pezzo dell’articolo di Alberto per introdurre un piccolo sondaggio:
Creare delle documentazioni, nonostante possa sembrare un’attività spesso inutile e molto laboriosa, presenta notevoli vantaggi sia quando si lavora in team sia quando si lavora da soli. Ovviamente lavorando in team una documentazione esaustiva non può che giovare sui componenti in quanto hanno una base di partenza che permette loro di capire il comportamento del codice scritto da altri. Nel caso invece si lavori ad un progetto in solitaria una buona documentazione è utile non tanto durante lo sviluppo ma nei periodi successivi, quando magari si riprende in mano il codice per eventuali bug-fix o implementazioni di nuove funzionalità: è molto frequente infatti dimenticarsi cosa si è fatto in passato.
Credo che in pochi dissentiranno, ma quanti mettono in pratica? Non solo per JavaScript, ovvio, sapeste quante volte avrei voluto trovarmi davanti a commenti HTML ben fatti e significativi…
Categoria: Scripting | Permalink
Commenti
1
Concordo pienamente.
Personalmente ho sempre preferito la documentazione cartacea, fatta di schizzi, disegni, flussi, ecc.
Mi sembra che scrivere spunti di documentazione sulla carta prende molto meno tempo che scrivere le stesse cose in modo strutturato al computer.
In definitva, sulla carta ci riesco, in un database o roba simile non riesco mai a trovare tempo.
2
Commento codice php e javascript usando le convenzioni di javadoc, con php poi alle volte genero la documentazione con lo strumento phpdoc.
Per quanto riguarda l’html… no, non lo commento, l’unica cosa che faccio è mettere un commento al tag di chiusura specificando qual’è il div di partenza (ad esempio ), questa è l’unica cosa che mi torna comoda nell’html.
Ciao
3
Tra parentesi avevo scritto:
<– chisura div#test –>
4
Scrivo anche io la documentazione del codice PHP con la sintassi JavaDoc da quando uso Eclipse, poiché l’IDE la interpreta e mi facilita tantissimo con l’autocompletamento.
# - postato da kEsoNNo - 13 Novembre 2008 - 02:18