123 lines
5.9 KiB
Markdown
123 lines
5.9 KiB
Markdown
# Python 评论:它是什么以及如何创建
|
||
|
||
> 原文:[https://python.land/introduction-to-python/python-comment](https://python.land/introduction-to-python/python-comment)
|
||
|
||
Python 注释是 Python 程序源代码中的解释。除了提供信息之外，它不做任何事情，并且被 Python 解释器忽略。在本文中，您将了解到:
|
||
|
||
* Python 注释是什么，
|
||
* 如何在 Python 代码中添加注释，
|
||
* 写评论时常见的陷阱是什么
|
||
|
||
目录
|
||
|
||
|
||
|
||
* [什么是 Python 注释？](#What_is_a_Python_comment "What is a Python comment?")
|
||
* [单行 Python 注释](#A_single-line_Python_comment "A single-line Python comment")
|
||
* [多行 Python comment](#Multiline_Python_comment "Multiline Python comment")
|
||
* [注释掉代码](#Comment_out_code "Comment out code")
|
||
* [Python 注释的常见错误](#Common_mistakes_with_Python_comments "Common mistakes with Python comments")
|
||
* [继续学习](#Keep_learning "Keep learning")
|
||
|
||
|
||
|
||
## 什么是 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 中，我们通过以散列符号开始一行来创建注释: **#** 。这种符号被称为数字符号，哈希，或(在北美的用法)英镑符号。不管你叫它什么，这就是它的样子:
|
||
|
||
```py
|
||
# This is a single-line comment in Python
|
||
print('Hello')
|
||
# And here's another one!
|
||
```
|
||
|
||
## 多行 Python comment
|
||
|
||
添加多行注释没有特殊的方法，也称为块注释。相反，您只需在每一行的开头使用散列符号，就像这样:
|
||
|
||
```py
|
||
# 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](https://www.buymeacoffee.com/pythonland)**. It's much appreciated and allows me to keep working on this site!
|
||
|
||
为了注释掉 Python 中的代码，我们再次使用散列符号:
|
||
|
||
```py
|
||
# This code is disabled for now
|
||
# if password == 'welcome123':
|
||
# allow_access()
|
||
```
|
||
|
||
**提示:**在大多数 ide 和编辑器中，您可以通过选择所有行并按下 **Ctrl + /** 来注释掉多行代码块。您可以通过完全相同的操作来反转操作。
|
||
|
||
## Python 注释的常见错误
|
||
|
||
很多程序员在注释时都会犯一些错误。所以，我们来探讨这些，希望你不会犯！
|
||
|
||
### 使用太多注释
|
||
|
||
你应该把注释的使用限制在绝对必要的范围内。这是为什么呢？
|
||
|
||
有一个概念叫做自文档化代码。这意味着你的代码可读性强，易于理解，几乎不需要注释或文档。如果你的代码是可读的，并且不需要注释，那么它会更紧凑，更容易阅读。因此，如果您总是努力编写自文档化的代码，并且只求助于注释来解释更高级或不明显的东西，那将是最好的。
|
||
|
||
编写自文档化的代码应该有自己的文章，但是有三个要点已经很有帮助了:
|
||
|
||
1. 给你的 [Python 变量](https://python.land/introduction-to-python/variables)起个名字，让它们包含的内容一目了然。例如，不要只给你的清单命名为`m`或`m_list`，而要像`member_list`那样称呼它。
|
||
2. 用简洁的方式命名您的 [Python 函数](https://python.land/introduction-to-python/functions)，清楚地描述它们做什么。
|
||
3. 创建只做一件事的短函数。如果他们做不止一件事，把他们分成多个功能。一旦开始使用单元测试，短函数也更好。
|
||
|
||
### 陈述明显的事实
|
||
|
||
许多初级程序员倾向于陈述显而易见的事情。换句话说，他们在评论中描述他们将要做的事情。你可能也想这样做，尤其是当一门语言对你来说是新的时候，作为对你自己的一个提示。
|
||
|
||
以下是一些显而易见的例子:
|
||
|
||
```py
|
||
# 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](https://python.land/deep-dives/python-docstring) 的教程感兴趣。 |