python - 文档字符串与评论

Question

我对 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 中输入函数应该做什么的示例，以及“类型” contract'，该部分显示您输入的类型以及函数将返回的类型。

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

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

Answer 1

看来你的老师是如何设计程序的粉丝；)

我会将其视为为两个不会总是重叠的不同受众写作。

首先是文档字符串；这些适用于那些将使用您的代码而不需要或想知道它是如何工作的人。文档字符串可以变成实际的文档。考虑官方 Python 文档 - 每个库中有什么可用以及如何使用它，没有实现细节(除非它们直接与使用相关)

其次是代码内注释；这些是为了向想要扩展代码的人(通常是你!)解释正在发生的事情。这些通常不会变成文档，因为它们实际上是关于代码本身而不是使用。现在，关于什么是好的评论(或缺乏评论)的观点与程序员一样多。我个人添加评论的经验法则是:

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

由于您是在学术环境中进行编码，而且听起来您的讲师会很冗长，所以我想说顺其自然。使用代码注释来解释你是如何做你在设计秘诀中所说的。