二十二、Python中函数的注释 在Python中，函数注释是一种用于对函数的功能、参数、返回值等关键信息进行说明的方式，它可以帮助开发者更好地理解代码，也方便后续代码的维护和协作开发。

在Python中，函数注释是一种用于对函数的功能、参数、返回值等关键信息进行说明的方式，它可以帮助开发者更好地理解代码，也方便后续代码的维护和协作开发。以下是关于Python函数注释的详细介绍：

1.函数文档字符串（Docstring）

• 基本格式与位置：
  • 函数的文档字符串通常放在函数定义的内部，作为函数体的第一条语句，使用三引号（""" 或 '''）括起来。例如：

  def my_function():
   """这是一个简单的函数文档字符串示例，用于描述函数的基本情况。"""
   pass

• 作用与意义：
  • 它可以清晰地阐述函数的用途，比如这个函数是用来解决什么问题、实现何种业务逻辑等。
  • 说明函数的参数情况，包括参数的含义、数据类型要求（虽然Python是动态类型语言，但可以在文档字符串里提示期望的类型）等。
  • 告知调用者函数的返回值情况，像返回的数据类型、返回值代表的具体含义等。

2.常用的文档字符串规范

• Google风格：
  • 参数说明：对于函数的每个参数，会按照如下格式进行说明：

  def calculate_area(length, width):
   """
   计算矩形的面积。
   Args:
   length: 矩形的长度，数据类型为数值类型（如int或float）。
   width: 矩形的宽度，同样为数值类型。
   Returns:
   矩形的面积，数据类型为数值类型，是length和width的乘积。
   """
   return length * width

  • 这里在Args部分，清晰列出每个参数的名称、含义以及期望的数据类型等信息，方便阅读代码的人知道该传入什么样的值。在Returns部分，则详细说明了返回值的情况。
• Numpy风格：
  • 它的格式如下示例：

  def add_numbers(a, b):
   """
   对两个数进行相加操作。
   Parameters
   ----------
   a : int or float
   第一个要相加的数。
   b : int or float
   第二个要相加的数。
   Returns
   -------
   result : int or float
   a和b相加的结果。
   """
   return a + b

  • 在Parameters部分按顺序对每个参数的名称、数据类型及含义描述，而Returns部分同样细致说明了返回值的相关关键信息，且通过特定的缩进和格式来增强可读性。
• reStructuredText风格：
  • 示例如下：

  def get_full_name(first_name, last_name):
   """
   根据给定的名和姓组合成完整姓名。
   :param first_name: 人的名，字符串类型。
   :param last_name: 人的姓，字符串类型。
   :return: 完整的姓名，格式为 "名 姓"，字符串类型。
   """
   return f"{first_name} {last_name}"

  • 利用特定的:开头来标注参数和返回值相关说明部分，对函数各关键要素进行阐释。

3.查看函数注释

• 在Python中，可以通过函数的__doc__属性来查看函数的文档字符串内容。例如：

  def greet(name):
   """向指定的人打招呼。"""
   print(f"Hello, {name}!")
  print(greet.__doc__)

  • 上述代码执行后，会打印出向指定的人打招呼。，也就是greet函数的文档字符串内容。

工具支持

• 有很多代码编辑器（如PyCharm等）和开发工具能够识别函数的文档字符串，并根据规范进行智能提示和展示，方便开发者在调用函数时快速了解其详细信息，无需频繁查看函数的具体实现代码，提高开发效率。

总之，合理使用函数注释可以让Python代码更加清晰易懂、易于维护，是编写高质量代码的重要环节。