Python基础之注释的用法

在Python中，注释是用来给代码添加解释、说明或者提醒的文字，它们不会被执行成对应的Python代码。注释是帮助程序员更好地理解代码，也是编写和维护代码过程中不可或缺的一部分。本文将介绍Python中注释的用法。

注释的两种方式

Python中有两种注释方式：单行注释和多行注释。

单行注释

单行注释以#开头，后面跟着注释内容。当Python解释器执行到#符号，它会忽略这个#符号后面的所有内容。单行注释通常用于解释一行代码或者单个语句。

# 这是一个单行注释

x = 1  # 这是另一个单行注释

多行注释

多行注释用于注释多行代码或者一段长文本。在Python中，多行注释使用三个引号（”’或”””）表示。Python解释器会忽略三引号之间的所有内容。

"""
这是一个多行
注释。
它可以用于注释
多行代码。
"""

'''
这也是一个多行
注释。
它也可以用于注释
多行代码。
'''

注释最佳实践

虽然注释可以使代码更容易理解，但是过渡的注释也会干扰代码的可读性。以下是Python中注释的最佳实践：

• 为变量、函数和类添加说明文档。对于每个变量、函数和类，添加文档说明是很有用的，这可以使其他人更容易理解代码，也有助于代码维护。
• 写简洁而有用的注释。注释应该要让代码更容易理解，而不是提供一些显而易见的信息，如变量名、函数名等。注释的重点应该是解释代码的非直观部分。
• 注释应该保持同步。如果代码更改了，注释应该及时更新，否则会引起混淆或误解。
• 使用多行注释，尤其是在文件顶部或函数顶部。使用多行注释做文件的文档说明或函数的文档说明具有很好的可读性和可维护性。

示例

# 计算圆的面积公式：S=πr²
pi = 3.14  # 定义π的值

def calculate_circle_area(radius:float) -> float:
    """
    计算圆的面积
    :param radius: 半径
    :return: 面积
    """
    area = pi * radius * radius  # 计算圆的面积
    return area

以上代码中，我们定义了全局变量pi用来存储π的值，然后定义了一个计算圆面积的方法，使用了单行注释为代码加注释，使用多行注释为函数添加了详细的文档说明，这样可以让其他人更容易理解代码。

def count_diamond_words(file_path:str) -> int:
    """
    统计文件中由菱形符号组成的单词数量
    :param file_path: 文件路径
    :return: 统计结果
    """
    diamond_words = set(["◆","◇","▲","△"])  # 预定义菱形符号集合
    count = 0  # 定义计数器

    with open(file_path,"r",encoding="utf-8") as f:
        for line in f:
            words = line.split()
            for word in words:
                if set(word) == diamond_words:
                    count += 1

    return count

以上代码中，我们定义了一个统计文件中由菱形符号组成的单词数量的函数，使用了多行注释为函数添加了详细的文档说明，这样可以让其他人更容易理解这个函数。函数中还使用了单行注释为代码加注释，并预定义了菱形符号集合，这样可以使代码更加简洁易懂。