您是否应该始终记录函数，即使是多余的（特别是 python）？

Question

我尝试使用具有活动性和描述性的函数名称，然后使用活动和描述性文本 (!) 对其进行记录。这会生成看起来冗余的代码。

python 中的简化（但不是那么不切实际）示例，遵循 numpy docstring 样式：

def calculate_inverse(matrix):
    """Calculate the inverse of a matrix.

    Parameters
    ----------
    matrix : ndarray
        The matrix to be inverted.

    Returns
    -------
    matrix_inv : ndarray
        The inverse of the matrix.

    """
    matrix_inv = scipy.linalg.inv(matrix)
    return matrix_inv

特别是对于 python，我已经阅读了 PEP-257 和 sphinx/napoleon 示例 numpy 和 Google 样式的文档字符串。我喜欢我可以为我的函数自动生成文档，但是对于像上面这样的冗余示例，“最佳实践”是什么？不应该简单地记录“明显”的类、函数等吗？ “显而易见”的程度当然会变得主观......

我想到的是开源的分布式代码。多位作者建议代码本身应该是可读的（calculate_inverse(A) 比 dgetri(A) 更好），但多个最终用户将从 sphinx 样式的文档中受益。

Answer 1

我一直遵循代码告诉你它做了什么的指导方针，添加了cmets来解释为什么它做某事.

如果你看不懂代码，你就没有生意看它，所以有（极端）：

index += 1   # move to next item

完全是浪费时间。对名为calculate_inverse(matrix) 的函数的评论也是如此，该函数声明它计算矩阵的逆矩阵。

而类似：

# Use Pythagoras theorem to find hypotenuse length.
hypo = sqrt (side1 * side1 + side2 * side2)

可能更合适，因为它添加了有关方程式来源的信息，以防您需要进一步调查。

真正应该为添加信息保留注释，例如用于计算逆的算法。在这种情况下，由于您的算法只是将工作交给scipy，因此完全没有必要。

如果您必须在此处有一个用于自动生成文档的文档字符串，那么对于这个非常简单的案例，我当然不会超越单行变体：

"""Return the inverse of a matrix"""

Answer 2

“总是”？绝对不是。尽量少评论。评论撒谎。他们总是撒谎，如果他们不撒谎，那么他们明天就会撒谎。这同样适用于许多文档。

您应该为您的代码编写 cmets/文档的唯一时间 (imo) 是当您向客户/客户提供库时，或者您处于开源项目中时。在这些情况下，您还应该有一个严格的标准，这样就不会有任何歧义，应该和不应该记录什么，以及如何记录。

在这些情况下，您还需要建立关于谁负责更新文档的工作流程，因为他们将始终与代码不同步。

因此，总而言之，如果您能提供帮助，请永远不要评论/记录。如果你必须（因为发布库/做开源），请正确执行（tm）。

Answer 3

清晰、简洁、写得很好且位置正确的 cmets 通常很有用。但是，在您的示例中，我认为代码在没有 cmets 的情况下是独立的。它可以双向进行。评论范围从需要和优秀到完全无用。

这是一个重要的话题。您应该阅读 Robert Martin 等人 (2008) 的“Clean Code: A Handbook of Agile Software Craftsmanship”中关于 cmets 的章节。第 4 章“注释”以这样的断言开头，“使用少量 cmets 的清晰而富有表现力的代码远优于使用大量 cmets 的杂乱和复杂的代码。与其把时间花在写解释你造成的烂摊子的 cmets 上，不如把它花在清理烂摊子上。”本章继续对 cme​​ts 进行了精彩的讨论。

Answer 4

是的，您应该始终记录函数。

许多答案都写了评论你的代码，这是非常不同的。我说的是文档字符串，它 document 你的界面。

文档字符串很有用，因为您可以在 python 解释器中获得交互式帮助。例如，

import math
help(math)

向您显示以下帮助：

    ...
    cos(...)
        cos(x)

        Return the cosine of x (measured in radians).

    cosh(...)
        cosh(x)

        Return the hyperbolic cosine of x.
    ...

请注意，尽管 cos 和 cosh 非常熟悉（并且完全重复了 C math.h 中的函数），但它们仍被记录在案。对于 cos，它明确声明它的参数应该是弧度。对于您的示例，了解 matrix 可能是什么会很有用。它是一个数组数组吗？一个元组的元组，或者一个 ndarray，正如您在其正确的文档中正确写的那样？矩形矩阵或零矩阵适合吗？

另一个“熟悉”的函数是 os 中的 chdir，它的文档如下：

    chdir(...)
        chdir(path)

        Change the current working directory to the specified path.

坦率地说，并不是标准库模块中的所有函数都被记录在案。我在 os 中发现了一个类 statvfs_result 的未记录方法：

     |  __reduce__(...)

也许它仍然是您应该记录的一个很好的例子。我承认我忘记了 reduce 是做什么的，所以我不知道这个方法。更熟悉的 __eq__、__ne__ 仍然记录在该类中（如 x.__eq__(y) <==> x==y）。

如果你不记录你的函数，你的模块的帮助将如下所示：

    calculate_inverse(matrix)

函数会更多地聚集在一起，因为文档字符串占用了额外的垂直空间。

为看不到您的代码的人编写一个文档字符串。如果函数真的很简单，那么文档字符串也应该很简单。它将让人相信该函数确实很简单，并且不会从该未记录的函数中引发任何意外（如果他们不费心编写文档，他们是否有能力和负责编写好的代码，真的吗？）

PEP 和其他准则的精神是代码应该对所有人都有益。 我很确定有人会遇到困难，这对你来说是显而易见的。 我（目前）用我的笔记本电脑写东西，屏幕不是很大，在 vim 中只有一个窗口，但我按照 PEP 8 写，says：“限制所需的编辑器窗口width 使得并排打开多个文件成为可能，并且在使用在相邻列中显示两个版本的代码审查工具时效果很好”。 PEP 257 recommends docstrings 可以很好地与 Emacs 的填充段落配合使用。

所以，我不知道什么时候不写文档字符串是值得的。但是，由于 PEP 和指南只是建议，如果您的函数不会被很多人使用，如果您将来不会使用它，并且如果您不想编写好的代码（在最少）。