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...