5.9 KiB
Python 评论:它是什么以及如何创建
原文:https://python.land/introduction-to-python/python-comment
Python 注释是 Python 程序源代码中的解释。除了提供信息之外，它不做任何事情，并且被 Python 解释器忽略。在本文中，您将了解到:
- Python 注释是什么，
- 如何在 Python 代码中添加注释，
- 写评论时常见的陷阱是什么
目录
什么是 Python 注释？
让我们从定义注释的确切含义开始:
Comment
A comment is an explanation in the source code of a Python program. Comments are added with the purpose of making source code easier for humans to understand. They are ignored by the Python interpreter.
因此，简而言之，注释可以帮助你和你的代码的其他读者更好地理解它。
单行 Python 注释
在 Python 中，我们通过以散列符号开始一行来创建注释: # 。这种符号被称为数字符号，哈希，或(在北美的用法)英镑符号。不管你叫它什么，这就是它的样子:
# This is a single-line comment in Python
print('Hello')
# And here's another one!
多行 Python comment
添加多行注释没有特殊的方法，也称为块注释。相反，您只需在每一行的开头使用散列符号，就像这样:
# This is a multi-line comment in Python,
# there's not much difference with single-
# line comments, as you can see!
在 Python(或任何语言，就此而言)中，最好编写清晰易懂的代码。所以如果你做得很好，你不应该经常需要多行注释！
注释掉代码
程序员经常使用的一种模式是临时注释掉代码。一个人想要这样做的原因有无数。这里仅举几个例子:
- 一项功能现在不能工作，但是你计划以后再工作，所以你不想放弃它
- 有一段可供选择的代码，您以后可能会用到，所以您可以把它作为一个提示留在注释中
- 你在重构你的代码，意味着你在清理代码。通常，这是一个创建更多更小的函数的过程，而您还没有完全准备好丢弃旧代码。
Thank you for reading my tutorials. I write these in my free time, and it requires a lot of time and effort. I use ads to keep writing these free articles, I hope you understand! Support me by disabling your adblocker on my website or, alternatively, buy me some coffee. It's much appreciated and allows me to keep working on this site!
为了注释掉 Python 中的代码，我们再次使用散列符号:
# This code is disabled for now
# if password == 'welcome123':
# allow_access()
**提示:**在大多数 ide 和编辑器中，您可以通过选择所有行并按下 Ctrl + / 来注释掉多行代码块。您可以通过完全相同的操作来反转操作。
Python 注释的常见错误
很多程序员在注释时都会犯一些错误。所以，我们来探讨这些，希望你不会犯！
使用太多注释
你应该把注释的使用限制在绝对必要的范围内。这是为什么呢？
有一个概念叫做自文档化代码。这意味着你的代码可读性强，易于理解，几乎不需要注释或文档。如果你的代码是可读的，并且不需要注释，那么它会更紧凑，更容易阅读。因此，如果您总是努力编写自文档化的代码，并且只求助于注释来解释更高级或不明显的东西，那将是最好的。
编写自文档化的代码应该有自己的文章，但是有三个要点已经很有帮助了:
- 给你的 Python 变量起个名字，让它们包含的内容一目了然。例如，不要只给你的清单命名为
m或m_list，而要像member_list那样称呼它。 - 用简洁的方式命名您的 Python 函数，清楚地描述它们做什么。
- 创建只做一件事的短函数。如果他们做不止一件事，把他们分成多个功能。一旦开始使用单元测试，短函数也更好。
陈述明显的事实
许多初级程序员倾向于陈述显而易见的事情。换句话说，他们在评论中描述他们将要做的事情。你可能也想这样做，尤其是当一门语言对你来说是新的时候，作为对你自己的一个提示。
以下是一些显而易见的例子:
# Ask for the user's name
name = input('Name: ')
# Call the say_hi function
say_hi(name)
# Now we divide the user input by 100
result = input / 100
没有维护您的 Python 注释
编辑代码时，很容易忘记那里的注释。总是检查它们是否仍然适用，或者可能需要修改，因为您刚刚更改了代码。
忘记描述函数或类的注释是一个常见的错误，因为它们通常与您正在编辑的代码不太接近。重构代码后，总是要看看注释。
注释掉代码而不是移除它
如上所述，有时您需要注释掉代码。但这并不意味着你可以把它留在那里。在我作为程序员的职业生涯中，我见过太多注释掉的代码部分。这个的问题是没人敢碰它。你的同事肯定是有原因的，对吧？
不…你的同事可能只是忘记了。但是你能确定吗？因此，养成清理被注释掉的代码的习惯。
继续学习
你可能也会对我的关于 Python docstrings 的教程感兴趣。