42

我对python中的文档字符串和注释之间的区别有点困惑。

在我的课上，我的老师介绍了一种被称为“设计秘诀”的东西，一组步骤据说可以帮助我们学生更好地用 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 中输入函数应该做什么的示例，以及“类型协定”，显示您输入的类型以及函数将返回的类型的部分。

现在这一切都很好并且完成了，但是我们的任务要求我们也有注释来解释我们的函数的性质，使用标记“#”符号。

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

4

4 回答 4

47

It appears your teacher is a fan of How to Design Programs ;)

I'd tackle this as writing for two different audiences who won't always overlap.

First there are the docstrings; these are for people who are going to be using your code without needing or wanting to know how it works. Docstrings can be turned into actual documentation. Consider the official Python documentation - What's available in each library and how to use it, no implementation details (Unless they directly relate to use)

Secondly there are in-code comments; these are to explain what is going on to people (generally you!) who want to extend the code. These will not normally be turned into documentation as they are really about the code itself rather than usage. Now there are about as many opinions on what makes for good comments (or lack thereof) as there are programmers. My personal rules of thumb for adding comments are to explain:

  • Parts of the code that are necessarily complex. (Optimisation comes to mind)
  • Workarounds for code you don't have control over, that may otherwise appear illogical
  • I'll admit to TODOs as well, though I try to keep that to a minimum
  • Where I've made a choice of a simpler algorithm where a better performing (but more complex) option can go if performance in that section later becomes critical

Since you're coding in an academic setting, and it sounds like your lecturer is going for verbose, I'd say just roll with it. Use code comments to explain how you are doing what you say you are doing in the design recipe.

于 2013-09-29T08:34:47.377 回答
6

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

文档字符串

编写好的文档字符串（又名“文档字符串”）的约定在 PEP 257 中得到了永生。

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

PEP 257 描述了良好的文档字符串约定。请注意，最重要的是，结束多行文档字符串的 """ 应该单独一行，例如：

"""Return a foobang

Optional plotz says to frobnicate the bizbaz first.
"""

对于一个班轮文档字符串，请保持结束的“””在同一行。

注释

屏蔽评论

通常适用于它们后面的部分（或全部）代码，并且缩进到与该代码相同的级别。块注释的每一行都以 # 和一个空格开头（除非它是注释内的缩进文本）。

块注释内的段落由包含单个 # 的行分隔。

内联评论

谨慎使用内联注释。

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

内联注释是不必要的，如果它们陈述明显的话，实际上会分散注意力。

不要这样做：

x = x + 1 # 增加 x

但有时，这很有用：

x = x + 1 # 补偿边框

参考

于 2018-01-18T18:20:15.847 回答
4

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

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

于 2013-09-29T05:42:03.690 回答
3

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

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

对象的文档是通过在对象定义中包含一个字符串常量作为第一条语句来定义的。

它在源代码中指定，用于记录特定代码段，如注释。

与传统的源代码注释不同，文档字符串应该描述函数的作用，而不是如何。

所有函数都应该有一个文档字符串

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

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

  1. 可以通过程序 ( __doc__) 访问文档字符串，因为无法访问内联注释。
  2. 像 bpython 和 IPython 这样的交互式帮助系统可以在开发过程中使用文档字符串来显示文档。这样您就不必每次都访问该程序。
于 2013-09-29T05:42:12.763 回答