文档字符串

Question

我对python中docstrings和comments之间的区别感到有点困惑。

在我的课堂上，我的老师介绍了一种被称为“设计方法”的东西，这一系列步骤可以帮助我们学生在Python中更好地绘制和组织编码。据我所知，下面是我们遵循的步骤的一个例子 - 这就是呼叫设计配方（报价中的内容）：

def term_work_mark(a0_mark, a1_mark, a2_mark, ex_mark, midterm_mark):

    ''' (float, float, float, float, float) -> float

    Takes your marks on a0_mark, a1_mark, a2_mark, ex_mark and midterm_mark, 
    calculates their respective weight contributions and sums these 
    contributions to deliver your overall term mark out of a maximum of 55 (This
    is because the exam mark is not taken account of in this function)

    >>>term_work_mark(5, 5, 5, 5, 5)
    11.8
    >>>term_work_mark(0, 0, 0, 0, 0)
    0.0
    '''

    a0_component = contribution(a0_mark, a0_max_mark, a0_weight)
    a1_component = contribution(a1_mark, a1_max_mark, a1_weight)
    a2_component = contribution(a2_mark, a2_max_mark, a2_weight)
    ex_component = contribution(ex_mark, exercises_max_mark,exercises_weight)
    mid_component = contribution(midterm_mark, midterm_max_mark, midterm_weight)
    return (a0_component + a1_component + a2_component + ex_component + 
            mid_component)

据我所知，这基本上是一个文档字符串，在我们的文档字符串版本中，它必须包含三个内容：描述，如果在python shell中输入函数应该执行的操作的示例，以及'type contract'，一个部分，显示您输入的类型以及函数将返回的类型。

现在这一切都很好并且已经完成，但是我们的任务要求我们也使用令牌'＃'符号来解释我们的函数的性质。

所以，我的问题是，我还没有在文档字符串的描述部分解释我的函数会做什么？如果我基本上会告诉读者完全相同的事情，那么添加评论有什么意义呢？

Answer 1

看来你的老师是如何设计程序的粉丝;）

我要解决这个问题，因为他写的两个不同的观众并不总是重叠。

首先是文档字符串;这些是针对那些将要使用您的代码而不需要或不想知道它是如何工作的人。文档字符串可以转换为实际文档。考虑官方Python文档 - 每个库中可用的内容以及如何使用它，没有实现细节（除非它们与使用直接相关）

其次是代码内注释;这些是为了解释想要扩展代码的人（通常是你！）正在发生什么。这些通常不会变成文档，因为它们实际上是关于代码本身而不是用法。现在，对程序员的好评（或缺乏评论）有很多意见。我个人添加评论的经验法则是解释：

部分代码必须复杂。（想到优化）
您无法控制的代码的变通方法，否则可能会显得不合逻辑
我也会承认TODO，尽管我试图将其保持在最低限度
我已经选择了一种更简单的算法，如果该部分的性能后来变得至关重要，那么可以选择性能更好（但更复杂）的选项。

由于你是在学术环境中进行编码，而且听起来你的讲师很啰嗦，我只想说就是这样。使用代码注释来解释您在设计配方中如何做您所说的。

Answer 2

首先，要设置帖子格式，您可以使用您输入帖子的文字区域上方的帮助选项。

关于评论和文档字符串，doc字符串用于解释方法的总体用法和基本信息。另一方面，注释用于提供有关块或行的特定信息，＃TODO用于提醒您将来要执行的操作，变量定义等。顺便说一句，在IDLE中，当您将鼠标悬停在方法名称上时，文档字符串会显示为工具提示。

Answer 3

从此页面引用http://www.pythonforbeginners.com/basics/python-docstrings/

Python文档字符串（或docstrings）提供了一种方便的方法   将文档与Python模块，函数，类相关联，   和方法。

通过包含字符串常量来定义对象的docsting   对象定义中的第一个语句。

在源代码中指定使用，如注释一样   记录特定的代码段。

与文档字符串应描述的传统源代码注释不同   功能是什么，而不是如何。

所有功能都应该有docstring

这允许程序在运行时检查这些注释   实例作为交互式帮助系统，或作为元数据。

可以通过对象上的 __ doc __ 属性访问文档字符串。

可以通过程序（__doc__）访问文档字符串，因为无法访问内联注释。
bpython和IPython等交互式帮助系统可以使用docstrings在开发过程中显示docsting。因此，您不必每次都参观该计划。

Answer 4

我相信值得一提的是PEP8所说的，我的意思是纯粹的概念。

文档字符串

编写良好文档字符串的惯例（a.k.a。＆＃34; docstrings＆＃34;）在PEP 257中永生化。

为所有公共模块，函数，类和方法编写文档字符串。对于非公共方法，文档字符串不是必需的，但是您应该有一个注释来描述该方法的作用。此评论应出现在def行之后。

PEP 257描述了良好的文档字符串约定。请注意，最重要的是，＆＃34;＆＃34;＆＃34;结束多行文档字符串应该在一行上，例如：
"""Return a foobang

Optional plotz says to frobnicate the bizbaz first.
"""
对于一个班轮文档字符串，请保持结束＆＃34;＆＃34;＆＃34;在同一条线上。

谨慎使用内联评论。

内联注释是与语句在同一行的注释。内联注释应与语句中至少两个空格分隔。它们应该以＃和单个空格开头。

内联评论是不必要的，如果他们陈述显而易见的话，实际上会分散注意力。

不要这样做：

x = x + 1 ＃Increment x

但有时，这很有用：

x = x + 1 ＃补偿边框

Docstrings与评论

4 个答案:

文档字符串

评论

参考