[Python] Primi passi, anzi ancora prima :)

[cdimauro]

• 

Lo unit testing serve a documentare il codice fornendo proprio tutti gli esempi necessari a capire cosa si aspetta uno strumento (API, funzione, classe), in modo che l'utilizzatore ne sia pienamente consapevole in poco tempo.

No, lo unit test non serve a documentare il codice, se tu lo usi per documentare ne fai uso improprio (o secondario), ma non serve a quello.

Scusami, volevo dire che serve anche a quello.

Inoltre breaka l'encapsulation se i tuoi unit test (e lo fanno, dato che in un linguaggio dynamic typing lo si deve fare) testano anche le funzioni interne del codice e non solo l'interfaccia.

Non ho capito la parte evidenziata. Potresti essere più chiaro, per favore?

Intendo l'implementazione. In un linguaggio dynamic typing non hai l'ausilio del compilatore o interprete per testare la bontà di ogni singola riga di codice, quindi devi fare delle unità di testing anche per l'implementazione. In un linguaggio static typing è sufficiente solo testare l'interfaccia, perché alla fine gli effetti del typing si propagano nell'implementazione. In realtà sarebbe più corretto dire che l'implementazione è testata tramite il constraint dell'interfaccia.

In effetti spesso aggiungo anche dei test specifici per controllare che i tipi passati alla funzione sia quelli attesi.

E' anche per questo che non lo faccio: è troppo noioso scrivere documentazione, soprattutto sapendo che hai fatto un sacco di lavoro in tal senso mettendo in piedi una buona suite di test (che, nel mio caso, generalmente è circa il doppio del codice di produzione).

Sono due lavori totalmente diversi. Ti faccio un esempio banalissimo per farti capire che unit testing != documentazione:

Vogliamo testare una funzione per l'EOF nei file, lo facciamo con un file fisso di tot caratteri, dopo quei tot caratteri ci aspettiamo EOF, nel caso di feof() del C è:
while(1) {
  /* code */
  if ( feof(infile) )
    break;
}

Mentre il TestEOF() della mia dsarlib (nomi inventati) è:

while( ! TestEOF(infile) ) {
  /* code */
}

La posizione dell'EOF lo testo conteggiando il numero dei caratteri prima, se usassi loop diversi ci sarebbe un numero minore o maggiore rispetto a quello corretto.
Mi sai dire la differenza di come io nella mia libreria ho implementato il testing dell'EOF, a primo colpo d'occhio? Scommetto che senza una buona documentazione non ci riusciresti :-) (ed è normale).

Semplicemente il feof() del C ti dice se tu sei esattamente sulla posizione dell'EOF, mentre TestEOF() ti dice se il prossimo getch() fallirà perché sarà l'EOF.
L'unit testing ti aiuta a verificare se è corretto per come lo hai voluto implementare tu, ma per comunicarlo al programmatore devi documentarlo! Onestamente mi auguro di non trovare programmatori che pretendano che io capisca una certa implementazione leggendo il codice del testing come quello sopra!

Ti faccio un esempio di come controllo situazioni del genere nel mio codice:

Codice: [Seleziona]

function TestLogin() {
  AssertException('StringTooSmall', 'Login', '', 'Prova!');
  AssertException('StringTooLong', 'Login', str_repeat('N', 31), 'Prova!');
  AssertException('StringTooSmall', 'Login', 'Pippo', '');
  AssertException('StringTooLong', 'Login', 'Pippo', str_repeat('N', 31));

  NewUser();
  Login('Pippo', 'Pluto');
}E' in PHP perché è il primo che avevo davanti, ma comunque dovrebbe servire a rendere l'idea: riproduco lo scenario e lo testo.

In Python lavoro ancora meglio perché a ogni API/funzione/classe dedico una suite di test, e per ogni scenario esiste un test specifico con nome abbastanza indicativo (anche molto lungo, se capita) per far capire cosa sta testando. E poi ovviamente c'è il codice che esercita lo specifico scenario, e solo quello, che è abbastanza esplicativo.

Comunque capisco anche il tuo punto di vista. Certamente se dovessi distribuire il mio codice all'esterno sarei sicuramente costretto a scrivere la documentazione (perché è quello che normalmente si aspettano i programmatori; in particolare quelli che non sono avvezzi allo unit testing), e in tal caso opererei come hai scritto qui alla fine.

Posso chiederti, per curiosità, chi legge i file di unit testing a scopo di documentazione? :O

C'era un progetto chiamato Diamonds che abbiamo sviluppato nella sezione Programmazione del sito di hwupgrade. Fino a un po' di mesi fa c'era un sottoforum apposito in cui erano stati raccolti tutti i thread, ma visto che il progetto è poi stato abbandonato gli amministratori hanno deciso di spostare i thread all'interno della sezione Programmazione. Comunque se vedi nel link si possono ancora recuperare.

Qui trovi anche un thread in cui se ne parla, ma sono più interessanti i thread del progetto vero e proprio.

A proposito: se riesci a scaricarti i sorgenti non troverai commenti, a parte per i TODO.

Scrivere documentazione in corso d'opera è un'emerita stupidaggine: ci si ritroverebbe con due "codici" da gestire, mantenere, aggiornare, e che potrebbero anche trovarsi non aggiornati allo stesso tempo (il codice fa una cosa, e la documentazione ne dice un'altra). Cosa tutt'altro che scontata.

Il problema di syncare codice e documentazione è un problema reale, ma evitare di farlo fidati che è peggio

Sì, ho chiaro cosa intendi. Volevo soltanto dire che se si deve fare, è meglio farlo alla fine e non mentre si sviluppa, per i problemi che esponevo.

[Allanon]

• 

Logicamente di tutto quello che avete detto non è che abbia una grande esperienza, anche perchè con Python non ho neanche iniziato, posso solo dire che per i miei progetti non posso non documentare durante la stesura del codice (parlo di documentazione rivolta principalmente a me stesso e per le miei librerie) perchè a distanza di mesi non sarei più in grado di capire a colpo d'occhio cosa fa questo o quello, con quali parametri e limitazioni.
Poi man mano che effettuo delle modifiche modifico la documentazione (all'interno del codice stesso) e metto in coda una serie di brevi commenti su ciò che ho modificato/aggiunto.
Faccio questo perchè altrimenti non ne vengo più fuori  

Se poi devo pubblicare qualcosa è il momento di stendere la user doc, ma questo solo ed esclusivamente quando il progetto è concluso e stabile altrimenti diventa un secondo lavoro.

[cdimauro]

• 

Però non mi hai detto se a colpo d'occhio hai capito come è stato implementato il test dell'EOF.

Così com'era scritto no, non era assolutamente comprensibile. Avrei scelto un identificatore più descrittivo del tipo di controllo effettuato da quel pezzo di codice.

Ci sono situazioni complesse in cui non te ne puoi uscire con un semplice assert.

Francamente non so. L'esperienza con Diamonds mi porta a dire di no. Ma non posso nemmeno escludere a priori che in futuro non potrei trovarmi di fronte a un caso veramente tosto da formalizzare a livello di test.

Inoltre ci sono cose che non puoi documentare con l'unit testing, come degli internal che fanno riferimento a fatti di performance. Per esempio io pretendo di sapere se GC.Collect() mi invoca uno stop the world oppure è continuo o concorrente, perché nel primo caso sceglierei i momenti più adatti per farlo. Oppure ogni quanto i dati vengono automaticamente flushati in uno stream.

Concordo. Su questo genere di informazioni non c'è unit testing che tenga, ma è normale: non sono strettamente attinenti all'implementazione del codice.

L'unit testing serve per verificare la robustezza delle interfacce, e preferisco lasciarlo per quello.

Lo uso principalmente per quello, e ne sono soddisfattissimo, ma ti assicuro che in ambito Extreme Programming viene valorizzato anche a livello di documentazione. C'è una robusta e florida scuola di pensiero in merito.

Per la documentazione non devi mica scrivere un tema di 50 pagine, bisogna essere rigorosi, concisi ed inambigui. L'ultimo è importante e puoi raggiungerlo solo con i primi due

Concordo.

Logicamente di tutto quello che avete detto non è che abbia una grande esperienza, anche perchè con Python non ho neanche iniziato,

Tranquillo: il discorso che abbiamo fatto finora è generale e non riguarda soltanto Python.

posso solo dire che per i miei progetti non posso non documentare durante la stesura del codice (parlo di documentazione rivolta principalmente a me stesso e per le miei librerie) perchè a distanza di mesi non sarei più in grado di capire a colpo d'occhio cosa fa questo o quello, con quali parametri e limitazioni.
Poi man mano che effettuo delle modifiche modifico la documentazione (all'interno del codice stesso) e metto in coda una serie di brevi commenti su ciò che ho modificato/aggiunto.
Faccio questo perchè altrimenti non ne vengo più fuori  

Abbiamo due approcci completamente diversi. :mrgreen:

Per me è proprio grazie allo unit testing che posso spaziare da un progetto a un altro completamente diverso, effettuando modifiche e aggiungendo funzionalità con la consapevolezza e la sicurezza di realizzarli in tempi abbastanza "lineari" e rapidi, perché in poco tempo guardando i precisi test che m'interessano riesco a rendermi conto del lavoro che c'è da fare.

Comunque è una questione di pratica: più lavori in questo modo, più ne acquisisci la mentalità e ne apprezzi i frutti. 8-)

Se poi devo pubblicare qualcosa è il momento di stendere la user doc, ma questo solo ed esclusivamente quando il progetto è concluso e stabile altrimenti diventa un secondo lavoro.

Infatti. Farei così anch'io al tuo posto.