Prima di tutto bella discussione e grazie a tutti coloro che l'hanno
arricchita.
Io credo che prima di decidere se un commento è giusto o sbagliato bisogna
calarsi nel contesto.
Le best practices possono essere lette e rilette e ma mai capite. A me
capita spesso. Secondo me è uno degli arcani del mondo.
Chiediamoci anche come nascono le best practices?
Dall'esperienza dura sul campo? Da un principio di buon senso? Da una idea
balzana del un nuovo arrivato?
Se anche il papa mi dicesse di buttarmi dal ponte, prima di buttarmi
cercherei dentro di me se fosse giusto oppure no.
Cominciamo dal testo.
Si può leggere la divina commedia senza leggere le note, facendosi portare
dallo spirito poetico, oppure la si può leggere e studiare seguendo le note
passo passo. E se le note sono interessanti ti danno parecchio in più. (in
questo caso le note non sono state scritte dall'autore)
Ma che centra la divina commedia con un programma? nulla e tutto.
Entrambe sono costruite seguendo un linguaggio ed entrambe possono fare dei
giri pindarici e machiavellici.
Se potessimo leggere un programma scritto da un Dante Alighieri è probabile
che si riuscirebbe difficile a seguirlo ma chissà che bello che sarebbe.
Quindi chi scrive/programma conta. Non è che tutte le regole (o le best
practices) valgono a priori.
Tornando al contesto.
La parola programma che ho usato poc'anzi, è del tutto generica. Non è
che se scriviamo uno script, un videogioco, una web application, un sito
web, un prodotto, un framework o una libreria vigono le stesse regole. A
parte la finalità che è chiaramente diversa, è diverso il target.
Se scrivo una libreria, significa che qualcuno o anche me stesso la
riutilizzerà in futuro. Target programmatori. Come diceva Marco, vai di
docstring e doctest soprattutto sulle API pubbliche.
Se scrivo un framework la documentazione a forma di tutorial è la più
importante. Almeno per la maggior parte del target. Vedi Django è parecchio
utilizzato da programmatori e la sua forza è nei tutorial online, non certo
nei commenti del suo codice.
I commenti che sono importanti qui sono quelli che spiegano delle scelte,
spesso facendo riferimenti ai ticket o bug segnalati.
Su un framework come Django ad esempio non è che ti metti a commentare i
componenti architetturali, perché la maggior parte di essi è già nota dalla
documentazione online.
Se volessi studiare il codice dell'orm ad esempio sarebbe più utile un
documento architetturale che ti desse un immagine del design.
Non so voi, ma spesso mi capita di andare a spulciare il codice open, e
veramente poco spesso mi metto a leggere i commenti che non siano concisi.
(e anche non banali come: creo la classe, calcolo il risultato etc...)
Se scrivo un sito web, usando Django, certo non mi metto a commentare il
codice, forse una o due classi dove faccio delle scelte, ma la maggior
parte dei models, forms, admin, views, sono del tutto standard e non hanno
bisogno di commenti.
Il dominio, i modelli, sono del tutto inutili da commentare, meglio
scrivere una breve introduzione o un glossario che spieghi il dominio
piuttosto che spezzettare il discorso tra una classe e l'altra.
Se scrivo un prodotto, vuol dire che sarà venduto e che dovrò gestire la
sua evoluzione per diversi anni, andando dietro a decine o centinaia
(magari migliaia) di clienti. Il che significa che la miglior
documentazione tecnica sono i test. Inoltre se è un prodotto bisognerà
anche scrivere il manuale di utilizzo utente. (ma è un altra storia)
Solitamente se un prodotto o anche un progetto segue un particolare design
la documentazione utile è fatta da howto per i novizi. Se un nuovo
programmatore entra nel team deve essere in grado di lavorare nel progetto,
quindi howto end-to-end che lo seguono passo passo su casi d'uso semplici
che gli permettono di capire il complesso e vasto mondo.
In conclusione, i commenti sono importanti, ma non sono l'unica fonte di
documentazione. Sono essenziali se il target è un altro programmatore che
deve usare la tua libreria. Ma non sono minimamente sufficienti per
documentare il ciclo di vita di un prodotto.
Vanno usati con parsimonia, meno commenti che codice almeno un rapporto 1 a
5. (imho)
Inoltre lo so che è difficile, ma cerchiamo di scrivere codice come se
fossimo scrittori che aspirano al successo. L'estetica non è importante per
un calcolatore ma per un umano si.
___
Python mailing list
Python@lists.python.it
http://lists.python.it/mailman/listinfo/python
