信息

相较于既给⼈看也给编译器看的代码⽽⾔，注释完全就是写给⼈看的，因此注释要更偏向于⼈类阅读习惯。好的注释能够让⼈快速理解对象的逻辑或者含义，⽽不好的注释则有可能让阅读者产⽣另⼀种理解，从⽽把⼈带到坑⾥。

编程新⼿很容易产⽣两种截然不同的注释⻛格:

• 根本不知道要些注释或者些什么样的注释，你很难在他的代码⾥找到注释内容
• 很喜欢在代码⾥写上⾮常详细的注释，深怕⾃⼰或者阅读代码的其他⼈看不懂

使用注释之前

有些对象在起名的时候就已经具备了表达含义的能⼒，我们只需要⽤注释表达⼀些处理逻辑或者特别要留意的内容即可
如果你的注释需要写的很详细或者⽤来标注⼀个函数、⼀个变量的作⽤，那么你应该考虑的是给那个对象换⼀个更能表达含义的名字，⽽不是给它加上注释

实际上，如果能通过给变量起⼀个好名字能解决问题，那么直接起一个好名字更好

t = int(time.time()) * 1000 # 获取 13 位时间戳
timestamp_thirteen = int(time.time()) * 1000

变量注释

变量注释

Python 的变量或常量注释以 # 符号作为标记，后续跟随 1 个空格和对应的⽂字描述即可。如果在代码尾部编写注释时需要空出 2 个空格

# 如果在代码尾部编写注释时需要空出 2 个空格  
a = 1  # 注释

类型注释

⽤静态语⾔编写代码在定义对象时必须要指定对象的类型例如 int、 string、 []int 等，如果没有定义则会在编译时报错
虽然 Python 不是静态语⾔，也不⽀持编译时的类型检查，但是它⽀持类型注释

number: int = 1
name: str = "Recluse"

可以使用更加复杂的类型，不过需要引入

from typing import Tuple, List, Dict

coupons: Tuple[str, str, int] = ("z", "z", 5)
message: List[str, str, str, str, str] = ["a", "lb", "c", "d", "e"]
information: Dict[str: str] = {"a": "a", "b": "c"}

这个注释在函数的参数里也有应用

函数注释

函数体注释

函数注释常以 # 号或者 """ 号开头，其中 """ 号通常在函数名下的第⼀⾏开始，⽤以描述与函数相关的信息

def send(message, host, name):
    """ 消息推送器
    将消息推送到指定服务器的指定队列中
    :param message: 消息体
    :param host: 服务器地址
    :param name: 队列名称
    :return: 推送结果
    """
    pass

函数注释

函数注释（Function Annotations），是函数的一种额外的注释
主要用于提示函数的返回值类型

存在的原因

Python2 并没有对函数参数和返回值进行注释的标准方法
不少人创建了许多的库，尝试用不同的方式来解决这个问题。各个库使用的方法，实现的方法各不相同，使用起来相对麻烦
为了解决问题，统一标准。Python3 引入了 函数注释

使用方法

参数注释

在参数后以:标记，表示对特定参数的注释
可以填入包含 类型 或者 字符串

def foo(a:"我就是注释", b:"我也是注释"=5, c:int=2):
    pass

返回值注释

在括号以后以 -> 标记, 表示对函数返回值的注释。可以填入类型注释或者表达式

def a() -> list:
    return None

def b() -> max(1,5):
    return 2

访问函数注释

函数对象有一个名为 __annotations__ 的属性，它是一个映射（dict），用于将每个参数名（key）映射到其相关的注释（value）

注意： 映射中有一个特殊的 key，叫做“return”，仅当为函数的返回值提供注释时，才会显示该 key

回到上述示例，并检查它的注释：

def sum(a, b: int, c: 'The default value is 5' = 5) -> float:
    return a + b + c
type(sum.__annotations__)
>>><class 'dict'>
sum.__annotations__
>>>{'c': 'The default value is 5', 'return': <class 'float'>, 'b': <class 'int'>}

返回值的键是return。由于这个字符本身是Python的一个关键字，不存在”return参数”的可能性，所以并不会与其它参数发生冲突

多个注释

倘若，函数注释中要同时包含类型和帮助字符串，可以使用具有两个 key（例如：type 和 help）的 dict：

def div(
    a: dict(type=float, help='被除数'),
    b: dict(type=float, help='除数,必须不为0')
) -> dict(type=float, help='会得到a/b的结果'):
    return a / b

div.__annotations__
>>>{'a': {'type': <class 'float'>, 'help': '被除数'}, 'return': {'type': <class 'float'>, 'help': '会得到a/b的结果'}, 'b': {'type': <class 'float'>, 'help': '除数,必须不为0'}}

动态注释

__annotations__ 是函数的一个属性，是可以在程序运行时动态地修改的
你甚至可以在函数内部对它进行更改

def sum(a, b) -> 0:
    result = a + b
    sum.__annotations__['return'] += result
    return result

文件注释

⽂件注释通常写在⽂件的开头，后续才是代码内容
⽂件注释通常被⽤于表明法律或版权信息、作者介绍以及⽂件内容的相关信息
Python 的⽂件注释以 # 符号或者 """ 符号标记，通常情况下，单⾏内容⽤
# 符号标记，⽽多⾏内容⽤ """ 标记。⽂字的格式并没有要求，可以按照团队约定的⻛格或者⾃⼰的习惯编写