「false」であるブール関数の引数に付けるコメントを修正しますか？

いくつかのオープンソースプロジェクトから、次のコーディングスタイルを集めました

void someFunction(bool forget);

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

falseここで何を意味するのか、私はいつも疑っています。それは「忘れる」ことを意味しますか、それとも「忘れる」は対応するパラメーターを参照しますか（上記の場合のように）、「false」はそれを無効にすることを意味しますか？

どのスタイルが最も頻繁に使用され、曖昧さを避けるための最良の方法（またはいくつかのより良い方法）は何ですか？

投稿したサンプルコードでforgetは、フラグ引数のように見えます。（関数は純粋に仮説的なものであるため、確信が持てません。）

フラグ引数はコードの匂いです。関数は複数のことを行い、良い関数は1つのことだけを行う必要があることを示しています。

フラグ引数を回避するには、関数名の違いを説明する2つの関数に関数を分割します。

フラグ引数

serveIceCream(bool lowFat)

フラグ引数なし

serveTraditionalIceCream()
serveLowFatIceCream()

編集：理想的には、flagパラメーターを使用して関数を保持する必要はまったくありません。Fowlerがもつれた実装と呼ぶものに沿って、関数を完全に分離すると重複コードが作成される場合があります。ただし、パラメーター化された関数の循環的複雑度が高いほど、それを取り除くための引数は強くなります。

素人の言葉で：

• false リテラルです。
• あなたはリテラルを渡している false
• あなたはsomeFunction忘れないように言っています
• あなたが言っているsomeFunctionパラメータであることを忘れていることfalse
• あなたはsomeFunction覚えているように言っています

私の意見では、関数が次のようになった方が良いでしょう。

void someFunction(bool remember);

あなたはそれを呼び出すことができます

void ourFunction() {
  someFunction(true);
} 

または、古い名前を保持しますが、ラッパー関数を

void ourFunctionWithRemember() {
  someFunction(false);
} 

編集：

@Voracが述べたように、常にポジティブな言葉を使うよう努めてください。二重否定は紛らわしい。

パラメータには適切な名前を付けることができます。関数の名前を知らずに伝えるのは難しいです。私はコメントは、関数のオリジナルの著者によって書かれたと仮定し、それが合格何のリマインダーだったfalseにsomeFunction手段が、誰もがその後に沿って来て、それは一見ちょっと不明です。

使用して正の変数名を（Code Completeで推奨）ことは、このスニペットを読みやすくする最も単純な変更かもしれません。例えば

void someFunction(boolean remember);

その後ourFunction：

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

ただし、列挙型を使用すると、関数呼び出しがさらに理解しやすくなりますが、一部のサポートコードが犠牲になります。

public enum RememberFoo {
    REMEMBER,
    FORGET
}

...

void someFunction(RememberFoo remember);

...

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

someFunction何らかの理由で署名を変更できない場合、一時変数を使用するとコードも読みやすくなります。人間がコードを解析しやすくする以外の理由で変数を導入することで条件を単純化するようなものです。 。

void someFunction(boolean remember);

...

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

bool値が意味をなすように変数の名前を変更します。

名前があいまいであるため、関数に引数を説明するコメントを追加するよりも数百倍も優れています。

よりわかりやすい名前でローカルブール値を作成し、それに値を割り当てます。そうすれば、意味がより明確になります。

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

変数の名前を変更できない場合は、コメントをもう少し表現的にする必要があります。

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

Qt-Style APIについて言及しているこの正確な状況について言及している良い記事があります。そこでは、ブールパラメータトラップと呼ばれますと一見の価値があります。

その要点は次のとおりです。

1. boolが必要ないように関数をオーバーロードする方が良い
2. Esailijaが示唆するように、enumを使用するのが最善です

これは奇妙なコメントです。

コンパイラの観点からsomeFunction(false /* forget */);は、実際にはsomeFunction(false);（コメントは取り除かれます）。したがって、その行はsomeFunction、最初の（そして唯一の）引数を設定して呼び出すだけです。falseです。

/* forget */パラメータの名前です。おそらく、それは簡単な（そして汚い）リマインダーに過ぎず、実際にそこにいる必要はありません。あいまいさの少ないパラメーター名を使用するだけで、コメントはまったく必要ありません。

Cleanコードのアドバイスの1つは、不要なコメント^1の数を最小限に抑え（腐敗する傾向があるため）、関数とメソッドに適切な名前を付けることです。

その後、コメントを削除します。結局のところ、最新のIDE（Eclipseなど）は、関数の上にマウスを置くとコードでボックスをポップします。コードを見ると、あいまいさが解消されます。

¹いくつかの複雑なコードにコメントすることは問題ありません。

明らかなことを誤解するために、コメントは嘘をつくことができます。したがって、説明するためのコメントに頼らずに、コードを自己文書化する方が常に優れています。なぜなら、一部の人（おそらくあなた）がコメントに変更trueしfalseて更新しないからです。

APIを変更できない場合は、2つのオプションを使用します

• コードに関係なく、常にtrueになるようにコメントを変更します。これを一度だけ呼び出す場合、ドキュメントをローカルに保持するため、これは良い解決策です。

     someFunction（false / * true = forget、false = remember * /）; `

• 特に#definesを複数回呼び出す場合は使用してください。

     #define FORGET true
     #define REMEMBER false
     someFunction（REMEMBER）;

私はコメントを常に真にすることについての答えが好きですが、良いのですが、このコードの根本的な問題を見逃していると思います-それはリテラルで呼び出されています。

メソッドを呼び出すときはリテラルを使用しないでください。ローカル変数、オプションのパラメーター、名前付きパラメーター、列挙型-それらを避ける最善の方法は、言語と利用可能なものに依存しますが、それらを避けるようにしてください。リテラルには値がありますが、意味はありません。

C＃では、名前付きパラメーターを使用してこれを明確にしました

someFunction(forget: false);

またはenum：

enum Memory { Remember, Forget };

someFunction(Memory.Forget);

またはオーバーロード：

someFunctionForget();

またはポリモーフィズム `：

var foo = new Elephantine();

foo.someFunction();

命名は、ブール値のあいまいさを常に解決する必要があります。私は常にブール値に「isThis」や「shouldDoThat」のような名前を付けます。例えば：

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

等々。ただし、他の人のコードを参照する場合は、値を渡すときにコメントを残すのが最善です。