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 /拿破仑示例numpy和Google风格的文档字符串。我喜欢我可以自动为我的功能生成文档，但是什么是最佳实践＆＃34;对于上面的冗余例子？如果一个人根本不记录＆＃34;显而易见的＆＃34;课程，功能等？显而易见程度＆＃34;然后当然变得主观......

我想到了开源的分布式代码。多位作者建议代码本身应该是可读的（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，因此完全没必要。

如果必须在这里有自动生成文档的文档字符串，那么当然不会超出这个非常简单的案例的单行变体：< / p>

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

Answer 2

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

您应该为代码编写注释/文档的唯一时间（imo）是您向客户/客户发送库时，或者您是否在开源项目中。在这些情况下，您还应该有一个严格的标准，因此从来没有任何歧义应该和不应该记录，以及如何记录。

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

总而言之，永远不要评论/记录您是否可以提供帮助。如果你必须（因为发货库/做开源），请正确（tm）。

Answer 3

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

这是一个重要的主题。您应该阅读Robert Martin等人（2008年）的“清洁代码：敏捷软件工艺手册”中的评论章节。第4章“评论”从这个断言开始，“清晰而富有表现力的代码几乎没有任何评论，远远优于带有大量注释的混乱和复杂的代码。而不是花时间撰写解释你所造成的混乱的评论，花费它来清理混乱。“本章继续对评论进行了很好的讨论。

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 ，明确指出其自变量应以弧度为单位。对于您的示例，了解矩阵可能是有用的。它是一个数组数组吗？您在正确的文档中正确编写的元组元组或 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写道：“编辑器窗口的宽度使得可以并排打开多个文件，并且在使用在相邻列中显示两个版本的代码查看工具时效果很好。 PEP 257 recommends文档字符串，将与Emacs的填充段配合使用。

因此，我不知道什么时候不编写文档字符串是值得的好例子。但是，由于PEP和指南仅是建议，因此如果您的函数不会被很多人使用，如果您将来不再使用以及您不希望编写好的代码，则可以省略docstring。最少）。

你应该总是记录功能，即使冗余（特别是python）？

4 个答案: