要为“ false”的布尔函数参数添加正确的注释？

从一些开源项目中，我收集了以下编码样式

void someFunction(bool forget);

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

我一直对false这里的含义感到怀疑。它的意思是“忘记”，还是“忘记”是指它的相应参数（如上述情况），而“假”是要否定它？

哪种风格最常用，什么是避免歧义的最佳方法（或某些更好的方法）？

在您发布的示例代码中，它看起来像是forget一个标志参数。（我不能确定，因为函数纯粹是假设的。）

标志参数是代码的味道。它们表明一个功能不仅仅可以做一件事，而一个好的功能应该只能做一件事。

为避免使用flag参数，请将函数分解为两个函数，以说明函数名称的差异。

标记参数

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

重命名该变量，以便布尔值有意义。

这比添加注释来解释函数的参数要好一百万倍，因为名称不明确。

使用更具描述性的名称创建一个本地布尔值，然后为其分配值。这样，其含义将更加清楚。

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. 重载函数以便不需要布尔值会更好
2. 最好使用枚举（如Esailija所建议）

这是一个奇怪的评论。

从编译器的角度来看，someFunction(false /* forget */);实际上是someFunction(false);（注释已删除）。因此，该行所做的只是someFunction在第一个（也是唯一一个）参数设置为的情况下进行调用false。

/* forget */只是参数的名称。它可能只是快速（肮脏的）提醒而已，实际上并不需要在那里。只需使用不太模糊的参数名称，就根本不需要注释。

Clean代码的建议之一是最大程度地减少不必要的注释^1的数量（因为它们容易腐烂），并正确命名函数和方法。

接下来，我将删除评论。毕竟，当您将鼠标放在函数上时，现代的IDE（例如eclipse）会弹出一个带有代码的框。看到代码应该清除歧义。

¹评论一些复杂的代码是可以的。

显而易见，可以撒谎。因此，最好使代码自行记录而无需诉诸注释来解释，因为某些人（也许您）会更改true为false注释而不更新注释。

如果您无法更改API，那么我要使用2个选项

• 更改注释，使其始终为true，无论代码如何。如果只调用一次，这是一个很好的解决方案，因为它将文档保持在本地。

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

• 使用#defines，特别是如果您多次调用它。

     ＃定义忘记真
     #define REMEMBER false
     someFunction（REMEMBER）;

我喜欢关于使注释始终为true的答案，但是虽然不错，但我认为它忽略了此代码的根本问题-使用文字来调用它。

调用方法时应避免使用文字。局部变量，可选参数，命名参数，枚举-如何最好地避免使用它们取决于语言和可用的内容，但是请尽量避免使用它们。文字有价值，但没有意义。

在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){ ... }

等等。但是，当您引用别人的代码时，最好在传递值时留下注释。