Devo documentare un semplice progetto Unit Test?

4

Ho letto domande come questa: I test unitari sono realmente utilizzati come documentazione?

Riguardo ai commenti al codice; la mia ricerca finora mi sta dicendo:

1) Alcuni sviluppatori non gradiscono alcun commento sul codice e preferiscono leggere i nomi dei metodi del codice del test unitario per capire il codice.

2) Alcuni sviluppatori preferiscono i commenti al codice e i nomi dei metodi di test unitario per comprendere il codice

Ho usato lo strumento di documentazione di Sandcastle per documentare la mia API di progetto. Sto discutendo se usare Sandcastle per generare file .HTML per il mio progetto di unit test in modo che qualcun altro che li legge li capisca più rapidamente. È necessario o completo? Il mio istinto mi sta dicendo: documenta l'API con i commenti del codice, ma non documenta il progetto di test vero e proprio.

Il motivo per cui lo chiedo è perché ho letto ieri una domanda in cui un utente stava parlando di documentare il progetto di test spiegando che cosa fa ogni test in modo più dettagliato con Sandcastle.

    
posta w0051977 25.01.2018 - 17:05
fonte

4 risposte

1

Ci sono 2 aspetti sottilmente diversi nella documentazione dei test unitari.

  1. Il nome del test unitario dovrebbe essere descrittivo e loquace quanto tu possa farcela. Questo è non allo scopo di documentare il test, ma per fornire informazioni su un test fallito a un livello più alto. Se vedi un test fallito in un report, il nome ti spiegherà perché il codice non è riuscito e puoi andare direttamente al codice senza dover controllare il codice di test dell'unità per ottenere i dettagli. In altre parole, documenta lo scopo del test.

  2. Il codice di test unitario dovrebbe essere un codice chiaro e autodocumentante, come qualsiasi altra cosa. Dovrebbe avere solo commenti aggiuntivi se c'è qualcosa di complicato in corso; e con i test unitari, non dovrebbe esserci quasi mai qualcosa di complicato in corso.

Quindi, assolutamente no. Nessun commento estraibile formalizzato. L'uso di test unitari per "documentare" il comportamento del codice in prova deriva naturalmente dalla loro natura, come una raccolta di "esempi di frammenti di codice". Ma questi "frammenti di codice" non richiedono alcun commento aggiuntivo per questo scopo: basta leggere il codice.

    
risposta data 25.01.2018 - 23:29
fonte
1

Al momento nessuno legge documentazione per niente.

Diciamo che la documentazione di test è in realtà la cosa migliore del mondo e migliora la produttività del 1 miliardo percento.

Per realizzare questo vantaggio dovrai convincere la gente di questo fatto E anche convincerli che LORO devono essere personalmente la persona a leggerlo E che THEY personalmente trarrà vantaggio dalla lettura in termini di avanzamento di carriera.

Se trascorri del tempo scrivendo la documentazione del test (2018), stai scommettendo sul fatto che prima che il tuo prodotto diventi obsoleto o aggiornato il mondo si sia avvicinato al genio della documentazione di test e ti abbia lodato come un genio non celebrato. È lunga probabilità. Stai meglio scrivendo un blog a riguardo.

Se il tuo manager sta forzando a scriverlo, sta danneggiando direttamente la tua carriera e dovresti cambiare lavoro il più presto possibile.

Inoltre, continuo a incontrare i programmatori che ritengono che i test unitari siano una perdita di tempo. Aggiungere qualsiasi tipo di impedimento per scrivere più test, anche discutere di nominare o commenti non è il modo in cui vuoi andare. La guerra non è ancora vinta.

    
risposta data 25.01.2018 - 20:04
fonte
0

Non ha senso per me documentare i test unitari, a meno che:

  • Qualcuno non tecnico sta utilizzando il test unitario per comprendere le regole testate e la regola aziendale non può essere espressa nel nome del metodo perché è troppo complessa .

Ad esempio, si dispone di un calcolo che somma il credito, il debito e alcune imposte per calcolare il valore del prestito. Forse, in questo caso, questo test unitario:

/**
 * Verify if the user has credit enough to acquire a loan. 
 * The max loan possible is a sum between his credit, debit and Federal Tax 1 and 2 and a percentage.
 */
@Test
public void calculateLoan() { ... }

è migliore di questo:

@Test
public void calculateLoanVerifyingIfHasCreditBeforeAndSumDebitWithFederalTaxesAndPercentage() { ... }

Tuttavia, come ogni commento nel codice, c'è il rischio che questo commento non venga aggiornato quando il calcolo del prestito cambia in futuro :)

    
risposta data 25.01.2018 - 18:38
fonte
0

Questa è una buona domanda che è un argomento caldo e costante!

Mentre c'è del vero che nessuno legge la documentazione c'è anche la verità nell'averlo.

In Agile , l'obiettivo principale è avere una documentazione preziosa, ma poi la domanda diventa la documentazione di valore?

Per Modellazione agile "Crea un documento solo se soddisfa un obiettivo chiaro, importante e immediato degli sforzi complessivi del tuo progetto. Inoltre, ricorda che ogni sistema ha le proprie esigenze di documentazione uniche, che una dimensione non si adatta a tutte - l'implicazione è che tu sei non sarà in grado di seguire un "processo ripetibile" e sfruttare lo stesso set di modelli di documentazione su ogni progetto, almeno non se sei interessato a essere effettivamente efficace. "

La documentazione può anche essere preziosa per gli altri membri del team al di fuori dell'ingegneria, come il controllo qualità, l'automazione, gli analisti aziendali e il tuo manager o qualsiasi altro membro del team che fa affidamento sulla qualità dei test effettuati a tutti i livelli del processo.

Per la documentazione del test unitario, completare un commento di una riga come [// a / b test di / per X; il risultato atteso di y] non è solo prezioso per la condivisione delle informazioni a breve termine, ma anche con la crescita della base di codice i commenti aiuteranno a garantire che i test possano essere rapidamente aggiornati o cancellati e solo a rassicurare gli altri sulla qualità del codice.

    
risposta data 25.01.2018 - 19:09
fonte

Leggi altre domande sui tag