你是否应该总是记录函数，即使是多余的（特别是 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

我一直遵循这样的指导原则：代码告诉你它的作用，添加注释来解释它为什么做某事。

如果你看不懂代码，你就没有必要查看它，所以（在极端情况下）：

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

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

您应该为代码编写注释/文档的唯一时间（imo）是当您将库交付给客户/客户时或者您处于开源项目中时。在这些情况下，您还应该有一个严格的标准，这样就不会存在任何应该记录、不应该记录什么以及如何记录的含糊之处。

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

所以总而言之，如果可以的话，永远不要发表评论/记录。如果您必须这样做（因为运送库/进行开源），请正确执行（tm）。