[Python] Agile programming Robert Martin

[Marco Buttu]

On 30/09/2014 12:06, Carlos Catucci wrote:
> 2014-09-30 11:38 GMT+02:00 Manlio Perillo <manlio.perillo a gmail.com 
> <mailto:manlio.perillo a 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: mbuttu a oa-cagliari.inaf.it