W Clean Code autor podaje przykład

assertExpectedEqualsActual(expected, actual)

vs

assertEquals(expected, actual)

z tym pierwszym twierdzono, że jest bardziej przejrzysty, ponieważ eliminuje potrzebę pamiętania, gdzie idą argumenty i potencjalne niewłaściwe użycie z tego wynikające. Jednak nigdy nie widziałem przykładu poprzedniego schematu nazewnictwa w żadnym kodzie i cały czas go widzę. Dlaczego koderzy nie przyjmują tego pierwszego, jeśli jest, jak twierdzi autor, jaśniejszy od drugiego?

Ponieważ bardziej jest pisać, a więcej czytać

Najprostszym powodem jest to, że ludzie lubią pisać mniej, a kodowanie tych informacji oznacza więcej pisania. Czytając go, za każdym razem muszę przeczytać całość, nawet jeśli wiem, jaka powinna być kolejność argumentów. Nawet jeśli nie zna kolejności argumentów ...

Wielu programistów używa IDE

IDE często zapewniają mechanizm przeglądania dokumentacji dla danej metody poprzez najechanie myszką lub za pomocą skrótu klawiaturowego. Z tego powodu nazwy parametrów są zawsze pod ręką.

Kodowanie argumentów wprowadza powielanie i łączenie

Nazwy parametrów powinny już dokumentować, jakie są. Pisząc nazwy w nazwie metody, kopiujemy również te informacje w podpisie metody. Tworzymy również sprzężenie między nazwą metody a parametrami. Powiedz expectedi actualsą mylące dla naszych użytkowników. Przejście z assertEquals(expected, actual)do assertEquals(planned, real)nie wymaga zmiany kodu klienta za pomocą funkcji. Przejście od assertExpectedEqualsActual(expected, actual)do assertPlannedEqualsReal(planned, real)oznacza przełomową zmianę w interfejsie API. Lub nie zmieniamy nazwy metody, która szybko staje się myląca.

Używaj typów zamiast dwuznacznych argumentów

Prawdziwy problem polega na tym, że mamy niejednoznaczne argumenty, które można łatwo przełączać, ponieważ są tego samego typu. Zamiast tego możemy użyć naszego systemu typów i naszego kompilatora do wymuszenia prawidłowej kolejności:

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));

Można to następnie wymusić na poziomie kompilatora i zagwarantować, że nie będzie można uzyskać ich wstecz. Podchodząc z innej strony, to właśnie robi biblioteka Hamcrest dla testów.

Pytasz o długotrwałą debatę w programowaniu. Ile gadatliwości jest dobre? Ogólnie rzecz biorąc, programiści stwierdzili, że dodatkowa gadatliwość nazywania argumentów nie jest tego warta.

Gadatliwość nie zawsze oznacza większą przejrzystość. Rozważać

copyFromSourceStreamToDestinationStreamWithoutBlocking(fileStreamFromChoosePreferredOutputDialog, heuristicallyDecidedSourceFileHandle)

przeciw

copy(output, source)

Oba zawierają ten sam błąd, ale czy rzeczywiście ułatwiliśmy jego znalezienie? Zasadniczo najłatwiej jest debugować, gdy wszystko jest maksymalnie zwięzłe, z wyjątkiem kilku rzeczy, które zawierają błąd, a te są wystarczająco szczegółowe, aby powiedzieć ci, co poszło nie tak.

Istnieje długa historia dodawania gadatliwości. Na przykład istnieje ogólnie niepopularna „ notacja węgierska ”, która dała nam wspaniałe nazwy, takie jak lpszName. To na ogół poszło na marne w ogólnej populacji programistów. Jednak dodawanie znaków do nazw zmiennych członków (takich jak mNamelub m_Namelub name_) nadal cieszy się popularnością w niektórych kręgach. Inni całkowicie to porzucili. Zdarza mi się pracować na bazie kodu symulacji fizyki, której dokumenty w stylu kodowania wymagają, aby każda funkcja zwracająca wektor musiała określać ramkę wektora w wywołaniu funkcji ( getPositionECEF).

Być może zainteresują Cię niektóre języki popularne w Apple. Cel-C obejmuje nazwy argumentów jako część podpisu funkcji (funkcja [atm withdrawFundsFrom: account usingPin: userProvidedPin]jest zapisana w dokumentacji jako withdrawFundsFrom:usingPin:. To jest nazwa funkcji). Swift podjął podobny zestaw decyzji, wymagając umieszczenia nazw argumentów w wywołaniach funkcji ( greet(person: "Bob", day: "Tuesday")).

Autor „Czystego kodu” wskazuje na uzasadniony problem, ale jego sugerowane rozwiązanie jest raczej nieeleganckie. Zwykle istnieją lepsze sposoby poprawy niejasnych nazw metod.

Ma rację, że assertEquals(z bibliotek testowych jednostek stylu xUnit) nie wyjaśnia, który argument jest oczekiwany, a który rzeczywisty. To też mnie ugryzło! Wiele bibliotek testów jednostkowych zauważyło ten problem i wprowadziło alternatywne składnie, takie jak:

actual.Should().Be(expected);

Lub podobne. Co z pewnością jest o wiele wyraźniejsze niż, assertEqualsale także o wiele lepsze niż assertExpectedEqualsActual. I jest również o wiele bardziej składalny.

Próbujesz poprowadzić swoją drogę między Scyllą a Charybdą do jasności, starając się unikać bezużytecznej gadatliwości (znanej również jako bezcelowe wędrowanie), a także nadmiernej zwięzłości (znanej również jako tajemnicza zwięzłość).

Musimy więc przyjrzeć się interfejsowi, który chcesz ocenić, sposobowi na potwierdzenie-debugowanie, że dwa obiekty są równe.

1. Czy jest jakaś inna funkcja, którą może brać pod uwagę arianę i nazwę?
   Nie, więc sama nazwa jest wystarczająco jasna.
2. Czy typy mają jakieś znaczenie?
   Nie, więc zignorujmy ich. Już to zrobiłeś? Dobry.
3. Czy jest symetryczny w swoich argumentach?
   Niemal w przypadku błędu komunikat umieszcza reprezentację każdego argumentu we własnym miejscu.

Zobaczmy więc, czy ta niewielka różnica ma jakiekolwiek znaczenie i nie jest objęta istniejącymi silnymi konwencjami.

Czy zamierzeni odbiorcy są niewygodni, jeśli argumenty zostaną przypadkowo zamienione?
Nie, programiści dostają również śledzenie stosu i muszą sprawdzić kod źródłowy, aby naprawić błąd.
Nawet bez pełnego śledzenia stosu pozycja asercji rozwiązuje to pytanie. A jeśli nawet tego brakuje i nie jest to oczywiste z przesłania, które jest, co najwyżej podwaja możliwości.

Czy kolejność argumentów jest zgodna z konwencją?
Wydaje się, że tak jest. Choć w najlepszym razie wydaje się to słabą konwencją.

Różnica wygląda więc dość nieznacznie, a porządek argumentów objęty jest wystarczająco silną konwencją, aby każda próba umieszczenia go w nazwie funkcji miała negatywną użyteczność.

Często nie dodaje żadnej logicznej przejrzystości.

Porównaj „Dodaj” do „AddFirstArgumentToSecondArgument”.

Jeśli potrzebujesz przeciążenia, które, powiedzmy, dodaje trzy wartości. Co miałoby więcej sensu?

Kolejne „Dodaj” z trzema argumentami?

lub

„AddFirstAndSecondAndThirdArgument”?

Nazwa metody powinna przekazywać jej logiczne znaczenie. Powinien powiedzieć, co robi. Mówienie na poziomie mikro, jakie kroki należy podjąć, nie ułatwia czytelnikowi. W razie potrzeby nazwy argumentów dostarczą dodatkowych szczegółów. Jeśli nadal potrzebujesz więcej szczegółów, kod będzie dla Ciebie odpowiedni.

Chciałbym dodać coś, na co wskazują inne odpowiedzi, ale nie sądzę, by zostało to wyraźnie wymienione:

@puck mówi: „Nadal nie ma gwarancji, że pierwszy wymieniony argument w nazwie funkcji jest naprawdę pierwszym parametrem”.

@cbojar mówi „Używaj typów zamiast niejednoznacznych argumentów”

Problem polega na tym, że języki programowania nie rozumieją nazw: są one po prostu traktowane jako nieprzezroczyste, atomowe symbole. Dlatego, podobnie jak w przypadku komentarzy do kodu, niekoniecznie istnieje korelacja między nazwą funkcji a jej faktycznym działaniem.

Porównaj assertExpectedEqualsActual(foo, bar)z niektórymi alternatywami (z tej strony i gdzie indziej), takimi jak:

# 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)

Wszystkie mają większą strukturę niż pełna nazwa, co nadaje temu językowi coś nieprzejrzystego. Definicja i użycie funkcji zależy również od tej struktury, więc nie może ona zsynchronizować się z tym, co robi implementacja (jak nazwa lub komentarz może).

Kiedy napotykam lub widzę taki problem, zanim sfrustruję swój komputer, najpierw zastanawiam się, czy to „uczciwe” obwinianie maszyny. Innymi słowy, czy maszyna otrzymała wystarczającą ilość informacji, aby odróżnić to, czego chciałam od tego, o co prosiłam?

Takie wezwanie assertEqual(expected, actual)ma tak samo sens, jak assertEqual(actual, expected), więc łatwo jest je pomieszać, a maszyna pługa i zrobić coś złego. Jeśli użyliśmy assertExpectedEqualsActualzamiast, może to uczynić nas mniej prawdopodobne, aby popełnić błąd, ale to nie daje więcej informacji do urządzenia (nie można zrozumieć po angielsku, a wybór nazwy nie powinna mieć wpływu na semantykę).

To, co sprawia, że ​​podejście „ustrukturyzowane” jest bardziej preferowane, takie jak argumenty słów kluczowych, pola oznaczone etykietami, różne typy itp., Polega na tym, że dodatkowe informacje są również do odczytu maszynowego , dzięki czemu możemy wykryć nieprawidłowe użycie maszyny i pomóc nam zrobić wszystko dobrze. assertEqualSprawa nie jest tak źle, skoro jedynym problemem byłoby niedokładne wiadomości. Bardziej złowrogi może być przykład String replace(String old, String new, String content), który łatwo pomylić z String replace(String content, String old, String new)którym ma zupełnie inne znaczenie. Prostym rozwiązaniem byłoby zabranie pary [old, new], która sprawiłaby, że błędy natychmiast spowodowałyby błąd (nawet bez typów).

Zauważ, że nawet w przypadku typów możemy nie powiedzieć „maszynie, co chcemy”. Na przykład anty-wzorzec zwany „programowaniem ciągłym” traktuje wszystkie dane jako ciągi znaków, co ułatwia pomieszanie argumentów (jak w tym przypadku), zapomnienie wykonania jakiegoś kroku (np. Ucieczkę), przypadkowe złamanie niezmienników (np. co nie do rozdzielenia JSON) itp.

Jest to również związane z „ślepotą logiczną”, w której obliczamy kilka wartości logicznych (lub liczb itp.) W jednej części kodu, ale przy próbie użycia ich w innej nie jest jasne, co tak naprawdę reprezentują, czy mamy pomieszane itp. Porównaj to np. z różnymi wyliczeniami, które mają opisowe nazwy (np. LOGGING_DISABLEDzamiast false) i które powodują komunikat o błędzie, jeśli się pomieszamy.

ponieważ eliminuje to konieczność pamiętania, gdzie idą argumenty

Czy to naprawdę Nadal nie ma gwarancji, że pierwszy wymieniony argument w nazwie funkcji jest naprawdę pierwszym parametrem. Lepiej to poszukaj (lub pozwól, aby IDE to zrobiło) i pozostań przy rozsądnych nazwach, niż ślepo polegaj na dość niemądrych nazwach.

Jeśli czytasz kod, powinieneś łatwo zobaczyć, co się stanie, gdy parametry zostaną nazwane tak, jak powinny. copy(source, destination)jest o wiele łatwiejszy do zrozumienia niż coś takiego copyFromTheFirstLocationToTheSecondLocation(placeA, placeB).

Dlaczego koderzy nie przyjmują tego pierwszego, jeśli jest, jak twierdzi autor, jaśniejszy od drugiego?

Ponieważ istnieją różne punkty widzenia na różne style i można znaleźć x autorów innych artykułów, które twierdzą inaczej. Zwariowałbyś, próbując śledzić wszystko, co ktoś gdzieś pisze ;-)

Zgadzam się, że kodowanie nazw parametrów w nazwach funkcji sprawia, że ​​pisanie i używanie funkcji jest bardziej intuicyjne.

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

Łatwo zapomnieć o uporządkowaniu argumentów w funkcjach i poleceniach powłoki, a wielu programistów polega na funkcjach IDE lub odwołaniach do funkcji z tego powodu. Posiadanie argumentów opisanych w nazwie byłoby wymownym rozwiązaniem tej zależności.

Jednak po napisaniu opis argumentów staje się zbędny dla następnego programisty, który musi przeczytać instrukcję, ponieważ w większości przypadków zostaną użyte zmienne nazwane.

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

Zwięzłość tego zwycięży większość programistów, a ja osobiście łatwiej mi to czytać.

EDYCJA: Jak wskazał @Blrfl, kodowanie parametrów wcale nie jest tak „intuicyjne”, ponieważ trzeba przede wszystkim zapamiętać nazwę funkcji. Wymaga to wyszukania odniesień do funkcji lub uzyskania pomocy z IDE, które prawdopodobnie dostarczy informacji o porządkowaniu parametrów.