|
|
注释，每个程序员都写，但不是每个人都写得好。 一定有人跟你说，“注释是好的”和“你应该注释你的代码”。 但并非所有注释都适用这两句话。事实上，并不是所有的注释都是好的！ 有些注释会使代码变得更糟，而不是更好。
在本文中，我们将了解注释背后的一般原则以及如何在 Python 中注释代码（尽管这些原则适用于任何编程语言）。
事不宜迟，让我们开始吧！
避免WET注释
您可能听说过 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
def calc_area_of_circle(radius):
return radius * radius * math.pi是不是好很多！
避免描述HOW，更多地考虑WHY
还有一点，好的注释不应该描述代码的工作原理。 相反，它应该关注代码为什么做某事。
但是有人会问，注释不是用来帮助解释代码内部工作原理的吗？ 让我解释。
解释代码如何工作的注释有两个问题。
首先，解释某段代码如何工作的注释注定会过时。 注释引用的代码块越大，过时的速度就越快。一旦发生这种情况，注释就会变得非常有害。新来理解代码的人（或者甚至在你自己有一段时间没有看这段代码之后）很容易因为注释而误导代码在做什么。您可能会争辩说，一个好的开发人员应该仔细检查注释是否准确地描述准确——但反过来想想，注释是为我们写代码服务的，为什么还要费心把注释放在首位呢？
只是描述代码功能的注释的第二个问题是，它只是突出了代码编写的不太好的一种掩饰。我们应该努力重构我们的代码，使其可读且尽可能不言自明。的确有时候，重构代码使其通过阅读就可以清楚地知道它是如何工作的，非常困难。 但作为一般经验，描述代码如何工作的注释是很糟糕的。
注释代码为什么做某事，可以为读者提供更多更宏观的项目或功能背景。当修复bug或向代码添加新功能时，这会非常有帮助，因为开发人员将首先了解为什么这段代码会出现在这里，以及它试图解决什么问题。
总结
在本文中，我们了解了在 Python 中编写好的注释的一些规则。 这些规则足够通用，可以扩展到大多数编程语言中。通过遵循这些简单的规则，你的注释将会更加清晰。 最终，这将使你的代码变得更好。 |
|
回复
发帖
发表于 2023-1-9 16:01:45