Poprawny komentarz do argumentów funkcji boolowskich, które są „fałszywe”?

Z niektórych projektów typu open source zebrałem następujący styl kodowania

void someFunction(bool forget);

void ourFunction() {
  someFunction(false /* forget */);
}    

Zawsze mam wątpliwości, co falsetu oznacza. Czy oznacza to „zapomnieć”, czy też „zapomnieć” odnosi się do odpowiedniego parametru (jak w powyższym przypadku), a „fałsz” ma go zanegować?

Jaki styl jest używany najczęściej i jaki jest najlepszy sposób (lub kilka lepszych sposobów), aby uniknąć dwuznaczności?

W opublikowanym przez Ciebie przykładowym kodzie wygląda to jak forgetargument flagi. (Nie mogę być pewien, ponieważ funkcja jest czysto hipotetyczna).

Argumenty flagi są zapachem kodu. Wskazują, że funkcja wykonuje więcej niż jedną rzecz, a dobra funkcja powinna robić tylko jedną rzecz.

Aby uniknąć argumentu flagi, podziel funkcję na dwie funkcje, które wyjaśniają różnicę w nazwie funkcji.

Zgłoś argument

serveIceCream(bool lowFat)

Brak argumentu flagi

serveTraditionalIceCream()
serveLowFatIceCream()

edycja: Idealnie, nie musisz wcale obchodzić funkcji z parametrem flag. Są przypadki podobne do tego, co Fowler nazywa splątaną implementacją, w której całkowite oddzielenie funkcji tworzy zduplikowany kod. Jednak im wyższa cykliczna złożoność sparametryzowanej funkcji, tym silniejszy jest argument za jej pozbyciem się.

Słowami laika:

• false jest dosłowne.
• przekazujesz literał false
• mówisz, someFunctionżeby nie zapomnieć
• mówisz, someFunctionże parametr zapomnij tofalse
• mówisz someFunctionpamiętać

Moim zdaniem byłoby lepiej, gdyby funkcja była taka:

void someFunction(bool remember);

możesz to nazwać

void ourFunction() {
  someFunction(true);
} 

lub zachowaj starą nazwę, ale zmień funkcję opakowania na

void ourFunctionWithRemember() {
  someFunction(false);
} 

EDYTOWAĆ:

Jak stwierdził @Vorac, zawsze staraj się używać pozytywnych słów. Podwójna negacja jest myląca.

Parametr może być dobrze nazwany; trudno powiedzieć, nie znając nazwy funkcji. Zakładam, że komentarz został napisany przez oryginalnego autora funkcji, i to było przypomnienie o co przechodząc falsedo someFunctionśrodka, ale dla każdego, kto idzie potem, że to trochę niejasne na pierwszy rzut oka.

Użycie dodatniej nazwy zmiennej (sugerowanej w Code Complete ) może być najprostszą zmianą, która ułatwiłaby odczytanie tego fragmentu, np.

void someFunction(boolean remember);

następnie ourFunctionstaje się:

void ourFunction() {
    someFunction(true /* remember */);
}

Jednak użycie wyliczenia sprawia, że ​​wywołanie funkcji jest jeszcze łatwiejsze do zrozumienia, kosztem niektórych kodów pomocniczych:

public enum RememberFoo {
    REMEMBER,
    FORGET
}

...

void someFunction(RememberFoo remember);

...

void ourFunction() {
    someFunction(RememberFoo.REMEMBER);
}

Jeśli nie możesz zmienić podpisu z someFunctionjakiegokolwiek powodu, użycie zmiennej tymczasowej ułatwia również odczytanie kodu, coś w rodzaju uproszczenia warunków warunkowych poprzez wprowadzenie zmiennej bez żadnego innego powodu niż ułatwienie parsowania kodu przez ludzi .

void someFunction(boolean remember);

...

void ourFunction() {
    boolean remember = false;
    someFunction(remember);
}

Zmień nazwę zmiennej, aby wartość bool miała sens.

To milion razy lepsze niż dodawanie komentarza w celu wyjaśnienia argumentów funkcji, ponieważ nazwa jest niejednoznaczna.

Utwórz lokalny boolean o bardziej opisowej nazwie i przypisz mu wartość. W ten sposób znaczenie będzie bardziej wyraźne.

void ourFunction() {
    bool takeAction = false;  /* false means to forget */
    someFunction( takeAction );
}    

Jeśli nie możesz zmienić nazwy zmiennej, komentarz powinien być nieco bardziej wyrazisty:

void ourFunction() {
    /* false means that the method should forget what was requested */
    someFunction( false );
}    

Jest dobry artykuł, który wspomina o tej dokładnej sytuacji, ponieważ odnosi się do interfejsów API w stylu Qt. Tam nazywa się to Boolean Parameter Trap i warto ją przeczytać.

Jego istotą jest:

1. Lepsze jest przeciążenie funkcji, aby bool nie był potrzebny
2. Używanie wyliczenia (jak sugeruje Esailija) jest najlepsze

To dziwny komentarz.

Z punktu widzenia kompilatora someFunction(false /* forget */);jest faktycznie someFunction(false);(komentarz jest usuwany). Zatem wszystko, co robi linia, to wywołanie someFunctionz pierwszym (i jedynym) argumentem ustawionym na false.

/* forget */to tylko nazwa parametru. Prawdopodobnie jest to nic innego jak szybkie (i brudne) przypomnienie, które tak naprawdę nie musi tam być. Wystarczy użyć mniej dwuznacznej nazwy parametru, a komentarz w ogóle nie będzie potrzebny.

Jedną z rad Czystego kodu jest zminimalizowanie liczby niepotrzebnych komentarzy ¹ (ponieważ mają one tendencję do gnicia) oraz prawidłowe nazwanie funkcji i metod.

Następnie usunę komentarz. W końcu nowoczesne środowiska IDE (takie jak zaćmienie) wyskakują z kodem po najechaniu myszką na funkcję. Widzenie kodu powinno usunąć niejasności.

¹ Komentowanie złożonego kodu jest w porządku.

Aby pochwalić to, co oczywiste, komentarze mogą kłamać. Dlatego zawsze lepiej jest samokontrować kod bez uciekania się do komentarzy w celu wyjaśnienia, ponieważ pewna osoba (być może ty) zmieni się truenafalse i nie zaktualizować komentarz.

Jeśli nie możesz zmienić interfejsu API, skorzystaj z 2 opcji

• Zmień komentarz, aby zawsze był prawdziwy, niezależnie od kodu. Jeśli zadzwonisz tylko raz, jest to dobre rozwiązanie, ponieważ utrzymuje dokumentację lokalnie.

     someFunction (false / * true = zapomnij, false = zapamiętaj * /); `

• Użyj #defines, zwłaszcza jeśli wywołujesz go więcej niż jeden raz.

     # zdefiniować ZAPOMNIJ true
     # zdefiniować PAMIĘTAJ false
     someFunction (PAMIĘTAJ);

Podoba mi się odpowiedź na temat tego, aby komentarz zawsze był prawdziwy , ale choć dobrze myślę, że pomija podstawowy problem z tym kodem - nazywa się go dosłownie.

Powinieneś unikać używania literałów podczas wywoływania metod. Zmienne lokalne, parametry opcjonalne, parametry nazwane, wyliczenia - to, jak najlepiej ich uniknąć, będzie zależeć od języka i dostępnych opcji, ale staraj się ich unikać. Literały mają wartości, ale nie mają znaczenia.

W C # użyłem nazwanych parametrów, aby to wyjaśnić

someFunction(forget: false);

Lub enum:

enum Memory { Remember, Forget };

someFunction(Memory.Forget);

Lub przeciążenia:

someFunctionForget();

Lub polimorfizm`:

var foo = new Elephantine();

foo.someFunction();

Nazewnictwo powinno zawsze eliminować dwuznaczność dla boolean. Zawsze nazywam boolean coś takiego jak „isThis” lub „shouldDoThat”, na przykład:

void printTree(Tree tree, bool shouldPrintPretty){ ... }

i tak dalej. Ale gdy odwołujesz się do kodu innej osoby, najlepiej pozostaw komentarz podczas przekazywania wartości.