您可能听说过 Write Everything Twice 或 WET。 这是一个编码概念,在概念上与另一个称为 DRY 或不要重复自己的原则相反。所有这一切在注释的上下文中意味着一个好的注释不应该简单地重申代码正在做什么。
例如,考虑以下代码:
import time
def time_stuff(fun):
start_time = time.time()
fun()
end_time = time.time()
return end_time - start_time这个函数可以记录其他函数执行的时间,以秒为单位。 非常简单。
设想你要求一个初学者给你的项目中添加一些注释,他可能添加了以下内容:
import time
def time_stuff(fun):
# Record the start time
start_time = time.time()
fun()
end_time = time.time()
return end_time - start_time这是一个非常WET的注释。注释并没有添加任何有用的东西,真的只是重申了一些已经很明显的东西。像这样的注释没有任何益处。 在某些时候,函数会发生变化,注释也会过时。
那么它不仅没有带来任何开始的价值,而且如果有人更改函数并忘记更新公共部分的注释(这种情况一直发生),它会降低代码的可读性。
避免在代码会做的地方写注释
你知道什么样的代码比注释良好的代码更好吗?那就是不需要注释的代码。 这就是开发人员应该努力的方向。你可能会问“这有什么重要的”? 毕竟,您只需添加一两行注释即可快速向读者解释所有内容,从而避免他思考代码的功能所带来的麻烦。
原因是代码很少是一成不变的,很可能会随着时间的推移而进化。如果该代码依赖于拥有最新的注释以便读者有机会了解函数中发生了什么,那么维护这些注释就变得与维护代码一样重要和繁重。更改代码后很容易忘记更新注释。
那么我们如何重构我们的代码,以至于我们(经常)甚至不需要注释它呢?
例如,考虑以下代码:
def calc(x):
return x * x * 3.14那些还记得学校几何课的人可能会认出这里的公式是圆的面积。 所以函数 calc 的目的是,对于给定的半径 r ,计算圆的面积。
这个函数在代码可读性方面一点都不好。大部分人的直觉可能是像这样注释代码:
def calc(x):
# Calculate area of circle for radius x
return x * x * 3.14那是……更好。 但是该代码仍然可以改进。考虑一下我们是否重写代码本身,以便它可以作为文档一样的去使用。
毕竟,我们可以给函数和变量命名,所以我们不妨充分利用它并使它们有意义。 这样做通常比写任何注释都要好用得多。
让我们像这样重写函数:
import math