【python系列】python如何添加注释
在 Python 编程中，注释是不可或缺的一部分。无论是帮助自己日后理解代码，还是方便团队成员维护代码，良好的注释习惯都至关重要。本文将带你全面了解 Python 注释的用法和最佳实践，同时带你领略 Python 语言的核心哲学——Python 之禅。
一、什么是注释？
注释是程序中的说明性文字，不会被 Python 解释器执行。它的作用是帮助开发者理解代码逻辑或提供额外的背景信息。
二、Python 中的注释类型
Python 支持两种类型的注释：单行注释和多行注释。
1. 单行注释
用井号 # 开头的语句就是单行注释。
# 这是一个单行注释
print("Hello, Python!") # 输出问候语
- #后的内容会被忽略，只有代码部分会被执行。
- 用于解释单行代码或为代码块提供简单说明。
2. 多行注释
可以通过多行 # 或三引号（‘’’ 或 “”"）实现多行注释。
方法一：多行 #
# 这是多行注释的第一行
# 这是多行注释的第二行
# 这是多行注释的第三行
方法二：三引号
"""
这是多行注释的第一行
这是多行注释的第二行
这是多行注释的第三行
"""
注意：三引号的本质是多行字符串，如果没有被赋值或调用，Python 解释器会忽略它们。
三、文档字符串（Docstring）
文档字符串是一种特殊的注释，用于函数、类或模块的说明，通常写在它们的第一行，使用三引号包裹。
def greet(name):
"""
这是一个问候函数。
参数：
name (str): 被问候者的名字
返回值：
str: 问候语
"""
return f"Hello, {name}!"
- 提取文档字符串：可以通过 help() 函数查看。
help(greet)
四、注释的最佳实践
- 简明扼要：注释要清晰、简短，直接解释代码逻辑或背景。
- 差：# 这是一个函数
- 优：# 计算输入字符串的长度
- 紧邻相关代码：注释要尽量贴近其解释的代码。
- 避免多余注释：不要解释过于显而易见的代码。
- 差：x = x + 1 # 将 x 的值加 1
- 优：x = x + 1 # 更新计数器
- 保持同步：代码更新后别忘了同步更新注释。
- 文档字符串统一风格：为每个函数、类提供文档字符串，便于生成代码文档。
五、注释的实际应用
以下是一个实际案例，展示了如何使用注释提高代码可读性。
# 导入所需模块
import math
def calculate_circle_area(radius):
"""
计算圆的面积。
参数：
radius (float): 圆的半径
返回值：
float: 圆的面积
"""
# 如果半径为负数，返回 0
if radius < 0:
return 0
# 使用公式计算面积
return math.pi * radius ** 2
# 示例：计算半径为 5 的圆面积
print(calculate_circle_area(5)) # 输出 78.54
六、python之禅
Python之禅（The Zen of Python) 是一组影响 Python 设计哲学的简要原则，由 Tim Peters 编写。它以一种幽默的方式总结了 Python 的设计思想，强调代码的简洁性、可读性和优雅性。
在 Python 解释器中输入以下代码即可看到 Python 之禅的内容：
import this
执行后输出如下：
The Zen of Python, by Tim Peters
Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!
逐条解读 Python 之禅
-
美胜于丑
代码应当优雅而非混乱，让人赏心悦目。 -
显式优于隐式
不要依赖隐式行为，用明确的方式表达意图。 -
简单胜于复杂
简单的代码更易于理解和维护。 -
复杂优于臃肿
在需要解决复杂问题时，代码可以复杂，但不应过度堆砌。 -
扁平优于嵌套
避免深层次的嵌套结构，扁平化结构更易于阅读。 -
稀疏胜于紧凑
使用合理的空格和换行，避免代码密集难读。 -
可读性至关重要
代码是写给人读的，良好的可读性至关重要。 -
特例不足以打破规则
即使有特殊情况，也不应违背通用规则。 -
实用比纯粹更重要
解决问题比追求理论上的完美更重要。 -
错误永远不应悄无声息
错误应该被显式地捕获和处理，而不是忽略。 -
除非明确要求
如果有特殊需求，错误可以被有意地抑制。 -
面对模棱两可时，不要猜测
代码的行为应当明确，不应依赖猜测或模糊定义。 -
应有一种显而易见的方法
通常应该有一种优先的解决方法，这使得代码更一致。 -
尽管这种方法并非对所有人显而易见
这一条是对 Guido van Rossum（Python 的创造者）的幽默致敬。 -
现在总比永远好
行动起来比拖延等待更好。 -
虽然永远有时比马上更好
仔细考虑后实施比仓促行事更好。 -
难以解释的实现可能是个坏主意
如果代码难以用简单的语言解释，可能需要重新设计。 -
易于解释的实现可能是个好主意
简单直观的实现通常是优质的。 -
命名空间是一个极好的想法
命名空间使代码更清晰，防止变量冲突。
Python 之禅的价值
- 它是 Python 开发哲学的核心，指导了语言的设计和进化。
- 鼓励开发者写出简洁、可读的代码。
- 不仅适用于 Python 编程，也可以作为编程的一般原则。
Python 之禅并非严格的规则，而是编程的一种理念。通过理解和实践这些原则，你能更好地驾驭 Python 编程的艺术！
七、总结
良好的注释就像为代码配备了一本手册，帮助团队和自己快速理解代码逻辑，同时与 Python 之禅的哲学理念相呼应。
- 单行注释简明直接。
- 多行注释解释复杂逻辑。
- 文档字符串说明函数和类的用途。
让我们践行 Python 之禅的精神，写出简洁、优雅、可读性高的代码！ 😊
原文地址：https://blog.csdn.net/gaolc888/article/details/143824119
免责声明：本站文章内容转载自网络资源，如本站内容侵犯了原著者的合法权益，可联系本站删除。更多内容请关注自学内容网（zxcms.com）！