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

我尝试使用活动和描述性的函数名，然后用活动和描述性文本（！）记录这些函数名。这会生成冗余的代码

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，我已经阅读了sphinx/napoleon示例和Google风格的DocString。我喜欢为我的函数自动生成文档，但是对于上面这样的冗余示例，“最佳实践”是什么？是否应该简单地不记录“明显的”类、函数等？“明显性”的程度当然会变得主观

我想到的是开源的分布式代码。多位作者建议代码本身应该是可读的（

计算逆（A）

优于

dgetri（A）

），但多个最终用户将受益于斯芬克斯风格的文档。

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

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

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

---

总之，如果你能帮上忙，就永远不要评论/记录。如果必须这样做（因为提供libs/doing open source），请正确地执行（tm）。

我一直遵循代码告诉您它是做什么的准则，添加注释来解释它为什么要执行某些操作

如果你看不懂代码，你就没有必要看它，因此（极端情况下）：

这完全是浪费时间。对名为

计算逆（矩阵）

的函数的注释也是如此，该函数表示它计算矩阵的逆

鉴于：

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

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

注释实际上应该保留用于添加信息，例如用于计算逆的算法。在这种情况下，由于您的算法只是将工作交给

scipy

，因此完全没有必要

如果您必须在这里为自动生成的文档准备一个docstring，那么对于这个非常简单的情况，我当然不会超出单行程序变量：

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

---

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

---

这是一个重要的话题。您应该阅读Robert Martin和其他人（2008）撰写的“干净的代码：敏捷软件工艺手册”中关于评论的章节。第4章“注释”以这句话开头，“注释少的清晰而富有表现力的代码远远优于注释多的杂乱而复杂的代码。与其花时间写注释来解释所造成的混乱，不如花时间来清理混乱。”本章继续对注释进行了精彩的讨论。

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

很多答案都是关于注释代码的，这是非常不同的。我说的是docstring，它记录了您的接口

docstring很有用，因为您可以在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，它明确规定其参数应以弧度为单位。对于你的例子来说，了解矩阵是什么很有用。它是数组的数组吗？一个元组的元组，或者一个数组，正如您在适当的文档中正确地写的那样？矩形矩阵或零矩阵适合吗

另一个“熟悉”的功能是来自操作系统的chdir，其文档记录如下：

    chdir(...)
        chdir(path)

        Change the current working directory to the specified path.

坦率地说，并不是所有标准库模块中的函数都有文档记录。我在os中发现了一个类statvfs_结果的非文档化方法：

也许这仍然是一个很好的例子，说明为什么你应该记录。我承认我忘了reduce是做什么的，所以我不知道这个方法。更为熟悉的uuueq uuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuu

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

    calculate_inverse(matrix)

函数将更多地聚集在一起，因为docstring占用额外的垂直空间

为看不到您的代码的人编写文档字符串。如果函数真的很简单，那么docstring也应该很简单。它将使人们相信函数确实很简单，而且没有文档记录的函数不会产生任何意外的结果（如果他们不费心编写文档，他们是否有能力并且有责任生成好的代码呢？）

PEP和其他指南的精神是代码应该适合所有人。 我敢肯定，有人会有困难，这对你来说是显而易见的。 我（目前）在笔记本电脑上写东西时屏幕不是很大，在vim中只有一个窗口，但我写东西时遵循PEP 8的规定，即：“限制所需的编辑器窗口宽度，可以让多个文件并排打开，并且在使用代码复查工具（在相邻列中显示两个版本）时效果很好”。PEP 257文档字符串，可与Emacs的填充段落配合使用。

| __reduce__(...)

    calculate_inverse(matrix)