In Clean Code l'autore fornisce un esempio di

assertExpectedEqualsActual(expected, actual)

vs

assertEquals(expected, actual)

con il primo dichiarato più chiaro perché elimina la necessità di ricordare dove vanno gli argomenti e il potenziale abuso che ne deriva. Tuttavia, non ho mai visto un esempio del precedente schema di denominazione in nessun codice e vedo quest'ultimo per tutto il tempo. Perché i programmatori non adottano il primo se è, come afferma l'autore, più chiaro del secondo?

Perché è più da scrivere e più da leggere

Il motivo più semplice è che alle persone piace digitare di meno e codificare tali informazioni significa scrivere di più. Quando lo leggo, ogni volta che devo leggere tutto, anche se ho familiarità con quale dovrebbe essere l'ordine degli argomenti. Anche se non ha familiarità con l'ordine degli argomenti ...

Molti sviluppatori usano gli IDE

Gli IDE forniscono spesso un meccanismo per visualizzare la documentazione per un determinato metodo passando con il mouse o tramite una scorciatoia da tastiera. Per questo motivo, i nomi dei parametri sono sempre a portata di mano.

La codifica degli argomenti introduce duplicazione e accoppiamento

I nomi dei parametri dovrebbero già documentare ciò che sono. Scrivendo i nomi nel nome del metodo, stiamo duplicando anche quelle informazioni nella firma del metodo. Creiamo anche un accoppiamento tra il nome del metodo e i parametri. Dì expectede actualconfondi i nostri utenti. Passare da assertEquals(expected, actual)a assertEquals(planned, real)non richiede la modifica del codice client utilizzando la funzione. Passare da assertExpectedEqualsActual(expected, actual)a assertPlannedEqualsReal(planned, real)significa cambiare in modo sostanziale l'API. Oppure non cambiamo il nome del metodo, che diventa rapidamente confuso.

Usa tipi invece di argomenti ambigui

Il vero problema è che abbiamo argomenti ambigui che possono essere facilmente scambiati perché sono dello stesso tipo. Possiamo invece utilizzare il nostro sistema di tipi e il nostro compilatore per applicare l'ordine corretto:

class Expected<T> {
    private T value;
    Expected(T value) { this.value = value; }
    static Expected<T> is(T value) { return new Expected<T>(value); }
}

class Actual<T> {
    private T value;
    Actual(T value) { this.value = value; }
    static Actual<T> is(T value) { return new Actual<T>(value); }
}

static assertEquals(Expected<T> expected, Actual<T> actual) { /* ... */ }

// How it is used
assertEquals(Expected.is(10), Actual.is(x));

Questo può quindi essere applicato a livello di compilatore e garantisce che non è possibile ripristinarli. Avvicinandosi da una prospettiva diversa, questo è essenzialmente ciò che la libreria Hamcrest fa per i test.

Chiedete un lungo dibattito nella programmazione. Quanta verbosità è buona? Come risposta generale, gli sviluppatori hanno scoperto che non è valsa la pena la prolissità aggiuntiva che nomina gli argomenti.

La verbosità non significa sempre maggiore chiarezza. Tener conto di

copyFromSourceStreamToDestinationStreamWithoutBlocking(fileStreamFromChoosePreferredOutputDialog, heuristicallyDecidedSourceFileHandle)

contro

copy(output, source)

Entrambi contengono lo stesso bug, ma abbiamo effettivamente reso più facile trovare quel bug? Come regola generale, la cosa più semplice da eseguire il debug è quando tutto è al massimo conciso, tranne le poche cose che hanno il bug, e quelle sono abbastanza dettagliate per dirti cosa è andato storto.

C'è una lunga storia di aggiunta di verbosità. Ad esempio, c'è la " notazione ungherese " generalmente impopolare che ci ha dato nomi meravigliosi come lpszName. Ciò è generalmente caduto a margine della popolazione del programmatore generale. Tuttavia, l'aggiunta di caratteri ai nomi delle variabili dei membri (come mNameo m_Nameo name_) continua ad avere popolarità in alcune cerchie. Altri lo hanno abbandonato del tutto. Mi capita di lavorare su una base di codice di simulazione fisica i cui documenti di stile di codifica richiedono che qualsiasi funzione che restituisce un vettore deve specificare il frame del vettore nella funzione call ( getPositionECEF).

Potresti essere interessato ad alcune delle lingue rese popolari da Apple. Objective-C include i nomi degli argomenti come parte della firma della funzione (La funzione [atm withdrawFundsFrom: account usingPin: userProvidedPin]è scritta nella documentazione come withdrawFundsFrom:usingPin:. Questo è il nome della funzione). Swift ha preso una serie di decisioni simili, richiedendo di inserire i nomi degli argomenti nelle chiamate di funzione ( greet(person: "Bob", day: "Tuesday")).

L'autore di "Clean Code" sottolinea un problema legittimo, ma la sua soluzione suggerita è piuttosto inelegante. Di solito ci sono modi migliori per migliorare i nomi dei metodi poco chiari.

Ha ragione nel dire che assertEquals(dalle librerie di unit test di stile xUnit) non si chiarisce quale argomento sia l'atteso e quale sia l'effettivo. Anche questo mi ha morso! Molte librerie di unit test hanno notato il problema e hanno introdotto sintassi alternative, come:

actual.Should().Be(expected);

O simili. Che è sicuramente molto più chiaro di assertEqualsma anche molto meglio di assertExpectedEqualsActual. Ed è anche molto più compostabile.

Stai cercando di orientare il tuo percorso tra Scilla e Cariddi verso la chiarezza, cercando di evitare inutili verbosità (noto anche come vagabondaggio senza scopo) così come eccessiva brevità (nota anche come terseness criptico).

Quindi, dobbiamo guardare l'interfaccia che si desidera valutare, un modo per fare asserzioni di debug secondo cui due oggetti sono uguali.

1. C'è qualche altra funzione che potrebbe prendere in considerazione arità e nome?
   No, quindi il nome stesso è abbastanza chiaro.
2. I tipi hanno qualche significato?
   No, quindi ignoriamoli. L'hai già fatto? Buono.
3. È simmetrico nei suoi argomenti?
   Quasi, in caso di errore, il messaggio mette ogni rappresentazione degli argomenti nella propria posizione.

Quindi, vediamo se questa piccola differenza ha qualche significato e non è coperta dalle convenzioni forti esistenti.

Il pubblico previsto è disturbato se gli argomenti vengono scambiati involontariamente?
No, anche gli sviluppatori ottengono una traccia dello stack e devono comunque esaminare attentamente il codice sorgente per correggere il bug.
Anche senza una traccia dello stack completa, la posizione delle asserzioni risolve tale domanda. E se anche quello manca e non è ovvio dal messaggio che è quale, al massimo raddoppia le possibilità.

L'ordine degli argomenti segue la convenzione?
Sembra essere il caso. Anche se nella migliore delle ipotesi sembra una convenzione debole.

Pertanto, la differenza sembra piuttosto insignificante, e l'ordine degli argomenti è coperto da una convenzione sufficientemente forte che qualsiasi sforzo per metterlo nel nome-funzione ha utilità negativa.

Spesso non aggiunge alcuna chiarezza logica.

Confronta "Aggiungi" con "AggiungiFirstArgumentToSecondArgument".

Se hai bisogno di un sovraccarico che, diciamo, aggiunge tre valori. Cosa avrebbe più senso?

Un altro "Aggiungi" con tre argomenti?

o

"AddFirstAndSecondAndThirdArgument"?

Il nome del metodo dovrebbe trasmettere il suo significato logico. Dovrebbe dire cosa fa. Raccontare, a livello micro, quali passi prende non semplifica il lettore. I nomi degli argomenti forniranno ulteriori dettagli se necessario. Se hai ancora bisogno di maggiori dettagli, il codice sarà lì per te.

Vorrei aggiungere qualcos'altro che è accennato da altre risposte, ma non credo sia stato menzionato esplicitamente:

@puck dice "Non c'è ancora alcuna garanzia che il primo argomento menzionato nel nome della funzione sia davvero il primo parametro".

@cbojar dice "Usa tipi invece di argomenti ambigui"

Il problema è che i linguaggi di programmazione non capiscono i nomi: sono solo trattati come simboli atomici opachi. Quindi, come con i commenti sul codice, non esiste necessariamente alcuna correlazione tra il nome di una funzione e il modo in cui funziona effettivamente.

Confronta assertExpectedEqualsActual(foo, bar)con alcune alternative (da questa pagina e altrove), come:

# Putting the arguments in a labelled structure
assertEquals({expected: foo, actual: bar})

# Using a keyword arguments language feature
assertEquals(expected=foo, actual=bar)

# Giving the arguments different types, forcing us to wrap them
assertEquals(Expected(foo), Actual(bar))

# Breaking the symmetry and attaching the code to one of the arguments
bar.Should().Be(foo)

Tutti questi hanno più struttura del nome dettagliato, che dà al linguaggio qualcosa di non opaco da guardare. La definizione e l'utilizzo della funzione dipendono anche da questa struttura, quindi non può essere fuori sincrono con ciò che l'implementazione sta facendo (come può fare un nome o un commento).

Quando incontro o prevedo un problema come questo, prima di gridare frustrato al mio computer, per prima cosa mi chiedo se sia "giusto" dare la colpa alla macchina. In altre parole, alla macchina sono state fornite informazioni sufficienti per distinguere ciò che volevo da ciò che chiedevo?

Una chiamata come assertEqual(expected, actual)ha più senso assertEqual(actual, expected), quindi è facile per noi confonderli e per la macchina andare avanti e fare la cosa sbagliata. Se assertExpectedEqualsActualinvece lo usassimo, potrebbe renderci meno propensi a fare un errore, ma non fornisce più informazioni alla macchina (non capisce l'inglese e la scelta del nome non dovrebbe influire sulla semantica).

Ciò che rende più preferibili gli approcci "strutturati", come argomenti di parole chiave, campi etichettati, tipi distinti, ecc. È che le informazioni extra sono anche leggibili automaticamente , in modo che possiamo avere la macchina individuare usi errati e aiutarci a fare le cose nel modo giusto. Il assertEqualcaso non è poi così grave, poiché l'unico problema sarebbero i messaggi imprecisi. Un esempio più sinistro potrebbe essere String replace(String old, String new, String content), che è facile confondere con il String replace(String content, String old, String new)quale ha un significato molto diverso. Un semplice rimedio sarebbe quello di prenderne una coppia [old, new], il che renderebbe immediatamente gli errori un errore (anche senza tipi).

Nota che anche con i tipi, potremmo trovarci a non "dire alla macchina ciò che vogliamo". Ad esempio l'anti-pattern chiamato "programmazione tipicamente stringa" tratta tutti i dati come stringhe, il che rende facile confondere gli argomenti (come in questo caso), dimenticare di fare qualche passo (es. Fuga), per rompere accidentalmente invarianti (es. rendendo JSON non analizzabile), ecc.

Ciò è anche correlato alla "cecità booleana", in cui calcoliamo un gruppo di booleani (o numeri, ecc.) In una parte del codice, ma quando si cerca di usarli in un'altra non è chiaro cosa rappresentino effettivamente, se li abbiamo mescolati, ecc. Confronta questo con ad esempio enumerazioni distinte che hanno nomi descrittivi (ad esempio LOGGING_DISABLEDpiuttosto che false) e che causano un messaggio di errore se le mescoliamo .

perché rimuove la necessità di ricordare dove vanno gli argomenti

Davvero? Non c'è ancora alcuna garanzia che il primo argomento menzionato nel nome della funzione sia davvero il primo parametro. Quindi meglio cercare (o lasciare che il tuo IDE lo faccia) e rimanere con nomi ragionevoli che fare affidamento ciecamente su un nome abbastanza sciocco.

Se leggi il codice dovresti vedere facilmente cosa succede quando i parametri sono nominati come dovrebbero essere. copy(source, destination)è molto più facile da capire di quanto non piaccia copyFromTheFirstLocationToTheSecondLocation(placeA, placeB).

Perché i programmatori non adottano il primo se è, come afferma l'autore, più chiaro del secondo?

Perché ci sono diversi punti di vista su stili diversi e puoi trovare x autori di altri articoli che affermano il contrario. Saresti impazzito cercando di seguire tutto ciò che qualcuno scrive da qualche parte ;-)

Concordo sul fatto che la codifica dei nomi dei parametri in nomi di funzioni rende la scrittura e l'utilizzo di funzioni più intuitive.

copyFromSourceToDestination( // "...ahh yes, the source directory goes first"

È facile dimenticare l'ordinamento degli argomenti nelle funzioni e nei comandi della shell e per questo motivo molti programmatori si affidano alle caratteristiche IDE o ai riferimenti alle funzioni. Avere gli argomenti descritti nel nome sarebbe una soluzione eloquente a questa dipendenza.

Tuttavia, una volta scritta, la descrizione degli argomenti diventa ridondante al prossimo programmatore che deve leggere l'istruzione, poiché nella maggior parte dei casi verranno utilizzate le variabili denominate.

copy(sourceDir, destinationDir); // "...makes sense"

La complessità di questo conquisterà la maggior parte dei programmatori e personalmente trovo che sia più facile da leggere.

EDIT: Come sottolineato da @Blrfl, la codifica dei parametri non è poi così "intuitiva" poiché è necessario innanzitutto ricordare il nome della funzione. Ciò richiede la ricerca di riferimenti alle funzioni o il supporto di un IDE che probabilmente fornirà comunque informazioni sull'ordinamento dei parametri.