8

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

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 样式的文档中受益。

4

4 回答 4

4

我一直遵循代码告诉你它做什么的准则，添加注释来解释它为什么做某事。

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

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"""
于 2015-10-08T15:32:18.043 回答
2

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

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

于 2015-10-08T17:47:27.277 回答
2

是的，您应该始终记录功能。

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

文档字符串很有用，因为您可以在 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，明确说明其参数应以弧度为单位。对于您的示例，了解矩阵可能是什么会很有用。它是一个数组数组吗？元组的元组或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 编写，它说：“限制所需的编辑器窗口宽度使得可以打开多个文件并排，并且在使用在相邻列中显示两个版本的代码审查工具时效果很好”。PEP 257推荐使用 Emacs 的填充段落的文档字符串。

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

于 2019-08-18T10:42:11.330 回答
2

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

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

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

所以总而言之，如果你能提供帮助，永远不要评论/记录。如果你必须（因为运送库/做开源），请正确地做（tm）。

于 2015-10-08T15:32:12.693 回答