Jer*_*emy 30 python comments docstring
我对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)
据我所知,这基本上是一个docstring,在我们的docstring版本中,它必须包含三件事:描述,如果你在python shell中输入你的函数应该做什么的例子,以及'类型契约',一个部分,显示您输入的类型以及函数将返回的类型.
现在这一切都很好并且完成了,但是我们的任务要求我们也使用令牌"#"符号来解释我们的函数的性质.
所以,我的问题是,我还没有解释我的函数将在docstring的描述部分中做什么？如果我基本上会告诉读者完全相同的事情,那么添加评论有什么意义呢？
小智 34
看来你的老师是如何设计程序的粉丝;)
我要解决这个问题,因为他写的两个不同的观众并不总是重叠.
首先是文档字符串; 这些是针对那些将要使用您的代码而不需要或不想知道它是如何工作的人.文档字符串可以转换为实际文档.考虑官方Python文档 - 每个库中可用的内容以及如何使用它,没有实现细节(除非它们与使用直接相关)
其次是代码内注释; 这些是为了解释想要扩展代码的人(通常是你!)正在发生什么.这些通常不会变成文档,因为它们实际上是关于代码本身而不是使用.现在,对程序员的好评(或缺乏评论)有很多意见.我个人添加评论的经验法则是解释:
既然你是在学术环境中编写代码,而且听起来你的讲师很啰嗦,那么我只想说它.使用代码注释来解释您在设计配方中如何做您所说的.
首先，为了格式化您的帖子，您可以使用您键入帖子的文本区域上方的帮助选项。
至于注释和文档字符串，文档字符串是为了解释方法的整体使用和基本信息。另一方面，注释旨在提供有关块或行的具体信息，#TODO 用于提醒您将来要做什么、变量的定义等。顺便说一句，在 IDLE 中，当您将鼠标悬停在方法名称上时，文档字符串会显示为工具提示。
我相信值得一提的是 PEP8 所说的，我的意思是，纯粹的概念。
编写好的文档字符串（又名“文档字符串”）的约定在 PEP 257 中永存。
为所有公共模块、函数、类和方法编写文档字符串。非公共方法不需要文档字符串，但您应该有一个注释来描述该方法的作用。此注释应出现在 def 行之后。
PEP 257 描述了良好的文档字符串约定。请注意，最重要的是，结束多行文档字符串的 """ 应该单独在一行上，例如：
Run Code Online (Sandbox Code Playgroud)"""Return a foobang Optional plotz says to frobnicate the bizbaz first. """对于单行文档字符串，请将结束的“””保留在同一行上。
阻止评论
通常适用于它们后面的一些（或全部）代码，并且缩进到与该代码相同的级别。块注释的每一行都以 # 和一个空格开头（除非它是注释内的缩进文本）。
块注释内的段落由包含单个 # 的行分隔。
内嵌注释
谨慎使用内联注释。
内联注释是与语句在同一行的注释。内联注释应与语句之间至少用两个空格隔开。它们应该以 # 和一个空格开头。
内联注释是不必要的，如果它们陈述显而易见的内容，实际上会分散注意力。
不要这样做：
x = x + 1 # 增加 x
但有时，这很有用：
x = x + 1 # 补偿边框
| 归档时间： |
|
| 查看次数： |
23892 次 |
| 最近记录： |