3小时入门Python——第二十课避免不良注释

  |   0 评论   |   0 浏览   |   给我丶鼓励

如您所知,Python 功能(所有 Python 程序员都喜欢)是其易于理解的语法。但是,除了语法本身之外,还有其他一些重要因素也可以提高程序的可读性。我们假设您已经熟悉注释以及它们如何帮助您学习新语言。

在实际程序中,注释随着程序变得越来越大和越来越复杂而变得尤为重要。没有它们,即使在编写程序后的几个月内,您甚至可能也会感到困惑,更不用说其他首次看到您的代码的开发人员了。但是,发表注释也有一个弊端,那就是说更多并不一定更好,我们也将在下面进行讨论。

什么时候不写注释?

这听起来可能很奇怪,但是有时候最好不要写注释。仔细地编写它们,确实可以提高程序的可读性,但这并不意味着您应尽可能包括它们。相反,许多程序员认为,好的代码起初不需要任何注释,因为它是如此透明和准确。这就是我们所有人都应针对的目标。因此,如果可以使代码变得不言自明,则注释是不必要的,最好更改代码。让我们重点介绍开发人员需要少注释的情况。

  • 如果注释解释了变量/函数,通常可以删除注释并显式命名变量/方法本身。比较以下代码行:
n = 0  # number of participants
participants_num = 0
  • 避免像下面这样写明显的注释。它们使您的代码变得多余,甚至难以阅读。您应该始终遵循 DRY(不要重复自己)的原则,而不要遵循 WET(对于更多的愤世嫉俗者,“将所有内容写两次”或“浪费每个人的时间”)。
age = 20  # age is 20
greeting = 'hello'  # assign 'hello' to greeting
  • 如果你看到一个方法来改变你的代码,以便意见将成为不必要的 -你应该做的。

也就是说,如果您可以避免发表注释-最好这样做。这样一来,您的代码将变得干净整洁,不会被不必要的细节所淹没,也不会变得更加复杂而不是使读者更加清晰。

如何写好注释?

现在,让我们谈谈决定写注释的情况。然后要记住的主要事情是,无论是 Future You 还是其他程序员,任何人都应该易于理解注释。以下是有关实现方法的一些提示:

  • 通常,注释应回答“ 为什么 ”而不是“ 什么 ”的问题。但是,它可能是有用的,适合初学者写评论为自己解释_什么_代码的功能,尤其是在使用刚学会的语法表达时,例如:
result = 15 % 4  # % is used for division with remainder
  • 确保您的注释不与代码冲突(这种情况比您想像的要多!)。错误的注释总比没有注释要糟糕。
# decrease the counter
counter += 1
  • 如果您修改了代码,请不要忘记更新注释。这只会使读者感到困惑,而不会帮助他们。在下面的示例中,变量“ counter”曾经被指定为“ i”;程序员在代码中更改了名称,但在注释中未更改。
# i is incremented in case of errors
counter += 1

遵循这些建议,您可以编写干净,有组织,易于理解且易于阅读的代码。

结论

在注释代码时,重要的是要知道在哪里画线。无论undercommented 方案可能很难理解,导致花费与这样的代码块的工作浪费和不愉快的时间。因此,您应该始终尝试仅在必要时谨慎地写评论。

学习做到这一点的最简单方法就是做到这一点。在您仅开始编码时就开始练习是个好主意,因为您会习惯它,并且到了解决一些更复杂的问题时,您就会知道如何正确编写注释。从现在开始,尝试在代码中包含简单的注释,以解释使您花一些时间才能理解的困难时刻。这也是要回有用的检查您的旧程序,看看他们(包括评论)怎么可能得到增强。


标题:3小时入门Python——第二十课避免不良注释
作者:给我丶鼓励
地址:https://blog.doiduoyi.com/articles/1592831064398.html

评论

发表评论