On 30/09/2014 12:06, Carlos Catucci wrote:
2014-09-30 11:38 GMT+02:00 Manlio Perillo <manlio.peri...@gmail.com
<mailto:manlio.peri...@gmail.com>>:
Senza passare tra due estremi opposti, i commenti servono se fanno
il loro dovere, ossia commentare del codice che altrimenti
potrebbe non essere di immediata comprensione. Per fare questo
devono essere scritti bene e tenuti aggiornati.
Il commento tra tripli apici subito dopo la dichiarazione di classe o
metodo in python che poi diviene l'output del comando help(<nome>) e'
secondo il mio modesto parere una delle cose piu' intelligenti che
esistano. Certo vanno scritti bene, e aggiornati.
In realta' il "commento tra tripli apici" non รจ un commento, ma una
stringa che viene utilizzata per creare della documentazione. Mentre i
commenti, come dice Manlio, servono per commentare il codice che
altrimenti potrebbe non essere di immediata comprensione (per lo
sviluppatore che deve mettere mano a quel codice), le docstring servono
per documentare le API, per cui sono utili all'utente finale per capire
come utilizzare un modulo, una funzione, una classe, ecc.
Per essere concreti, ecco un esempio che ritengo significativo, dove
risulta evidente quanto siano utili sia i commenti sia le docstring, se
scritti avendo chiaro in mente il loro scopo:
https://hg.python.org/cpython/file/3.4/Lib/statistics.py
Se vogliamo sapere cosa fa statistics e come utilizzare le sue funzioni,
non ci occorre consultare della documentazione offline o peggio andare a
tentativi:
>>> import statistics # A partire da Python 3.4
>>> help(statistics)
>>> help(statistics.mean)
Per quanto riguarda l'aggiornamento della documentazione, anche su
questo punto statistics e' scritto in modo impeccabile, perche' riporta
degli eloquenti esempi interattivi. Come disse Tim Peters a suo tempo:
* gli esempi non hanno prezzo
* gli esempi che non funzionano sono peggio di quelli inutili
* gli esempi che funzionano alla fine diventano esempi che non funzionano...
Il modulo doctest consente di evitare che "gli esempi che funzionano"
diventino "esempi che non funzionano":
$ python -m doctest /usr/lib/python3.4/statistics.py -v
Trying:
mean([-1.0, 2.5, 3.25, 5.75])
Expecting:
2.625
ok
...
52 tests in 18 items.
52 passed and 0 failed.
Test passed.
Visto che ci siamo, riporto un'altra perla, che e' la PEP relativa a
questo modulo:
http://legacy.python.org/dev/peps/pep-0450/
--
Marco Buttu
INAF-Osservatorio Astronomico di Cagliari
Via della Scienza n. 5, 09047 Selargius (CA)
Phone: 070 711 80 217
Email: mbu...@oa-cagliari.inaf.it
_______________________________________________
Python mailing list
Python@lists.python.it
http://lists.python.it/mailman/listinfo/python
