记录函数时如何引用“True-like”和“False-like”？答案

【问题标题】：How to refer to "True-like" and "False-like" when documenting a function?记录函数时如何引用“True-like”和“False-like”？
【发布时间】：2018-11-23 19:28:15
【问题描述】：

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 可能会返回任何对象，当满足条件 XXX 时，该对象将在 if 语句中评估为 True。这样的可调用对象将是传递给foo 的完全有效的参数。

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

我的第一步是写类似“[...] must return an object that will beevaluate to True if ...”，但我发现它被混淆了。

【问题讨论】：

常用的指代方式是 truthy 和 falsey。但是，这实际上根本没有要求，因为bar() 返回的任何值要么是真要么是假。
对象如何评估为真或假通常被称为“真实性”。另外，falsey is often spelled falsy.
@JohnGordon 有一些例外，比如 numpy 数组。有关详细信息，请参阅this。
@timgeb 够公平的。
您可以说bool(bar()) 必须评估为True 或False？

标签： python code-documentation

【解决方案1】：

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

咳咳

当在if 语句中使用时，评估结果为True 的术语是“真实的”。在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”更多的是俚语，这次来自数学世界。它的意思是“当且仅当”。这些词在编程上下文中很常用，所以我希望大多数程序员都能理解它们；如果不是，truthy、falsy、falsey 和iff 在搜索引擎中搜索时都会得出各自正确的含义。

【讨论】：

@John Gordon：我确实看到了您的评论，但我很高兴将问题标记为已解决。

【解决方案2】：

我不确定这是否有标准，但基于 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

【讨论】：

冗长但安全。在某些情况下很好。
“评估为真（假）”也是我的答案

【解决方案3】：

我建议说“如果 XXX 必须返回 True，否则返回 False”就可以了。由于鸭子打字，我按照您的意图阅读此内容。此外，这似乎是 Python 标准库记录事物的标准。

事实上，如果您确实严格要求值是True 或False 并使用这种语言，那么我将在追踪这个错误的过程中遇到非常糟糕的一天！

正如其他人所说，如果您仍然担心，“真实”和“虚假”是很好的、易于理解的替代方案。

【讨论】：