记录函数时如何引用 "True-like" 和 "False-like"？

Question

Strongly related question.

在 python 中为我的函数编写文档字符串时，有时我想写一些关于参数规范的类似内容：

def foo(bar):
    """
    Do some stuff.

    bar : callable
        must return True if XXX and False otherwise.
    """

    if bar(...):
        ...  # code goes here

然而，这并不完全准确，因为在此示例中，bar 可能是 returning 任何对象，当条件满足时，该对象将在 if 语句中被评估为 True XXX 已完成。这样的可调用对象将是传递给 foo.

的完全有效的参数

我应该如何制定我的文档以反映 foo 并不严格要求 bar 的输出为布尔值？

我的第一步是写类似“[...] 必须 return 一个对象，如果...，该对象将被评估为 True”，但我发现它很混乱。

Answer 1

我不确定是否有这方面的标准，但基于 python 的 Truth Value Testing，您可能会安全地编写类似

的内容

def foo(bar):
    """
    Do some stuff.

    bar : callable
        when tested for truth value, return value should evaluate to True if and only if XXX.
    """

    if bar(...):
        ...  # code goes here

Answer 2

这是一个俚语问题！我一直想回答其中一个问题！

咳咳。

在 if 语句中使用时计算结果为 True 的术语是 "truthy"。在 if 语句中使用时计算结果为 False 的术语是 "falsy" 或 "falsey"。所以，你的文档可以这样写：

def foo(bar):
    """
    Do some stuff.

    bar : callable
        must return a truthy value iff XXX.
    """

    if bar(...):
        ...  # code goes here

"Iff" 更像是俚语，这次来自数学世界。意思是"if and only if"。这些词在编程环境中很常用，所以我希望大多数程序员都能理解它们；如果没有，truthy, falsy, falsey and iff 在搜索引擎中搜索时都会得出各自正确的含义。

Answer 3

我建议这样说很好 "must return True if XXX and False otherwise." 因为鸭子打字，我按照你想要的方式阅读这篇文章。此外，这似乎是 Python 标准库记录事物的标准。

事实上，如果你做严格要求值为True或False并使用这种语言，我的日子会很糟糕追踪这个错误！

正如其他人所说，如果您仍然担心，"truthy" 和 "falsy" 是很好的、易于理解的替代方案。

记录函数时如何引用 "True-like" 和 "False-like"？

How to refer to "True-like" and "False-like" when documenting a function?

python

code-documentation