Python 注释规范

一些关于 Python 的注释规范，来自 GPT.

Question: Python 打注释有什么比较标准的格式吗？就像 Java 里面的 @param 那种一样。

在 Python 中，虽然没有像 Java 中的 @param 等特殊标记，但有一些约定俗成的注释风格。以下是一些常见的注释格式：

1. 函数注释（Docstring）:

   	def my_function(param1, param2):
   	"""
   	Description of the function.
   	Parameters:
   	- param1: Description of param1.
   	- param2: Description of param2.
   	Returns:
   	Description of the return value.
   	"""
   	# 函数体

   这种注释风格被称为 Docstring，用于描述函数的功能、参数和返回值。可以使用三个双引号或三个单引号来定义多行字符串。

2. 行内注释:

   在代码中使用行内注释，通常使用 # 符号。

   result = x + y # This is a comment about the calculation

3. 块注释:

   在一段代码块的上方使用块注释，解释该块的功能。

   	# This block of code does XYZ
   	# ...

4. TODO 注释:

   用于标记需要完成或改进的部分。

   # TODO: Implement this feature

5. 标准库注释:

   针对标准库的使用，可以参考 PEP 484 中的类型提示规范。

   	from typing import List, Tuple
   	def my_function(param1: int, param2: str) -> List[Tuple[int, str]]:
   	"""
   	Description of the function.
   	Parameters:
   	- param1: Description of param1.
   	- param2: Description of param2.
   	Returns:
   	A list of tuples containing int and str.
   	"""
   	# 函数体

这些注释风格都是一些通用的建议，它们有助于提高代码的可读性和维护性。对于函数注释，特别是类型提示，在现代 Python 中越来越受到推崇，因为它们可以通过类型检查工具提供更好的代码智能提示和静态分析。