Richtiger Kommentar für boolesche Funktionsargumente, die "falsch" sind?

Aus einigen Open Source-Projekten habe ich den folgenden Codierungsstil zusammengetragen

void someFunction(bool forget);

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

Ich habe immer Zweifel, was falsehier bedeutet. Bedeutet es "vergessen" oder bezieht sich das "vergessen" auf den entsprechenden Parameter (wie im obigen Fall) und "falsch" soll es negieren?

Welcher Stil wird am häufigsten verwendet und wie lässt sich die Mehrdeutigkeit am besten (oder auf eine der besseren Arten) vermeiden?

In dem von Ihnen geposteten Beispielcode sieht es so aus, als ob forgetes sich um ein Flag-Argument handelt. (Ich kann nicht sicher sein, weil die Funktion rein hypothetisch ist.)

Flag-Argumente sind ein Codegeruch. Sie zeigen an, dass eine Funktion mehr als eine Sache tut und eine gute Funktion nur eine Sache tun sollte.

Teilen Sie die Funktion zur Vermeidung des Flags in zwei Funktionen auf, die den Unterschied im Funktionsnamen erklären.

Flag Argument

serveIceCream(bool lowFat)

Kein Flag-Argument

serveTraditionalIceCream()
serveLowFatIceCream()

edit: Im Idealfall müssen Sie eine Funktion mit dem Flag-Parameter überhaupt nicht beibehalten. Es gibt Fälle in der Art, wie Fowler eine verworrene Implementierung nennt, bei der eine vollständige Trennung der Funktionen zu doppeltem Code führt. Je höher jedoch die zyklomatische Komplexität der parametrisierten Funktion ist, desto stärker ist das Argument, sie loszuwerden.

Mit den Worten des Laien:

• false ist ein wörtliches.
• Sie übergeben ein wörtliches Wort false
• Sie sagen someFunction, nicht zu vergessen
• Sie sagen, someFunctiondass der Parameter vergessen istfalse
• du sagst someFunctionzu erinnern

Meiner Meinung nach wäre es besser, wenn die Funktion so wäre:

void someFunction(bool remember);

das kannst du so nennen

void ourFunction() {
  someFunction(true);
} 

oder behalten Sie den alten Namen bei, ändern Sie jedoch Ihre Wrapper-Funktion in

void ourFunctionWithRemember() {
  someFunction(false);
} 

BEARBEITEN:

Wie @Vorac sagte, bemühen Sie sich immer, positive Wörter zu verwenden. Doppelte Verneinung ist verwirrend.

Der Parameter kann einen guten Namen haben. es ist schwer zu sagen, ohne den Namen der Funktion zu kennen. Ich gehe davon aus, dass der Kommentar von den ursprünglichen Autor der Funktion geschrieben wurde, und es war eine Erinnerung daran, was vorbei falsein someFunctionMittel, sondern auch für alle später kommen zusammen, es ist ein wenig unklar , auf den ersten Blick.

Die Verwendung eines positiven Variablennamens (vorgeschlagen in Code Complete ) ist möglicherweise die einfachste Änderung, die das Lesen dieses Snippets erleichtert, z

void someFunction(boolean remember);

dann ourFunctionwird:

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

Durch die Verwendung einer Aufzählung wird der Funktionsaufruf jedoch auf Kosten eines unterstützenden Codes noch verständlicher:

public enum RememberFoo {
    REMEMBER,
    FORGET
}

...

void someFunction(RememberFoo remember);

...

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

Wenn Sie die Signatur aus someFunctionirgendeinem Grund nicht ändern können , vereinfacht die Verwendung einer temporären Variablen auch das Lesen des Codes, indem Sie eine Variable nur einführen, um den Code für den Menschen einfacher parsen zu können .

void someFunction(boolean remember);

...

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

Benennen Sie die Variable um, damit ein bool-Wert Sinn macht.

Dies ist millionenfach besser als das Hinzufügen eines Kommentars zur Erläuterung von Argumenten zu einer Funktion, da der Name nicht eindeutig ist.

Erstellen Sie einen lokalen Booleschen Wert mit einem aussagekräftigeren Namen und weisen Sie ihm den Wert zu. Auf diese Weise wird die Bedeutung klarer.

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

Wenn Sie die Variable nicht umbenennen können, sollte der Kommentar etwas aussagekräftiger sein:

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

Es gibt einen guten Artikel, der genau diese Situation erwähnt, da er sich auf Qt-Style-APIs bezieht. Dort heißt es The Boolean Parameter Trap und es ist eine Lektüre wert.

Der Kern davon ist:

1. Es ist besser, die Funktion zu überladen, damit der Bool nicht benötigt wird
2. Die Verwendung einer Aufzählung (wie Esailija vorschlägt) ist am besten

Dies ist ein bizarrer Kommentar.

Aus der Sicht des Compilers someFunction(false /* forget */);ist dies tatsächlich someFunction(false);(der Kommentar wird entfernt). In dieser Zeile wird also nur someFunctiondas erste (und einzige) Argument aufgerufen, das auf gesetzt ist false.

/* forget */ist nur der Name des Parameters. Es ist wahrscheinlich nichts weiter als eine schnelle (und schmutzige) Erinnerung, die nicht unbedingt da sein muss. Verwenden Sie einfach einen weniger mehrdeutigen Parameternamen, und Sie brauchen den Kommentar überhaupt nicht.

Einer der Ratschläge von Clean Code ist, die Anzahl unnötiger Kommentare ¹ zu minimieren (da sie zum Verrotten neigen) und Funktionen und Methoden richtig zu benennen.

Danach würde ich nur den Kommentar entfernen. Schließlich wird in modernen IDEs (wie Eclipse) ein Kästchen mit Code angezeigt, wenn Sie mit der Maus über die Funktion fahren. Das Sehen des Codes sollte die Mehrdeutigkeit beseitigen.

^{1 Das} Kommentieren von komplexem Code ist in Ordnung.

Um das Offensichtliche zu beleuchten, können Kommentare lügen. So ist immer besser , um Ihren Code selbsterklärend, ohne auf die Kommentare zurückgreifen zu erklären, weil einige Menschen (vielleicht Sie) ändern truezu falseund nicht den Kommentar aktualisieren.

Wenn Sie die API nicht ändern können, greife ich auf zwei Optionen zurück

• Ändern Sie den Kommentar so, dass er unabhängig vom Code immer wahr ist. Wenn Sie dies nur einmal aufrufen, ist dies eine gute Lösung, da die Dokumentation lokal bleibt.

     someFunction (false / * true = vergessen, false = erinnern * /); `

• Verwenden Sie #defines, insbesondere wenn Sie es mehrmals aufrufen.

     #define FORGET true
     #define REMEMBER false
     someFunction (REMEMBER);

Mir gefällt die Antwort, dass der Kommentar immer wahr ist , aber obwohl er gut ist, vermisse ich das grundlegende Problem mit diesem Code - er wird mit einem Literal aufgerufen.

Sie sollten die Verwendung von Literalen beim Aufrufen von Methoden vermeiden. Lokale Variablen, optionale Parameter, benannte Parameter, Aufzählungen - wie Sie sie am besten vermeiden, hängt von der Sprache und den verfügbaren Informationen ab. Versuchen Sie jedoch, sie zu vermeiden. Literale haben Werte, aber sie haben keine Bedeutung.

In C # habe ich benannte Parameter verwendet, um dies zu verdeutlichen

someFunction(forget: false);

Oder enum:

enum Memory { Remember, Forget };

someFunction(Memory.Forget);

Oder Überladungen:

someFunctionForget();

Oder Polymorphismus`:

var foo = new Elephantine();

foo.someFunction();

Die Benennung sollte immer die Mehrdeutigkeit für Boolesche Werte auflösen. Ich nenne Boolean immer so etwas wie 'isThis' oder 'shouldDoThat', zum Beispiel:

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

und so weiter. Wenn Sie jedoch auf den Code einer anderen Person verweisen, ist es am besten, beim Übergeben von Werten nur einen Kommentar zu hinterlassen.