写出良好的Python注释

Python注释

Python（更确切的说是Python3）注释可以分为块注释和行内注释、文档注释、类型注释，接下来我将粗略介绍这四种注释形式。

• 块注释和行内注释：简要介绍
• 文档注释：分别介绍模块、函数和类的文档注释、如何获取文档注释（代码中、IDE中）
• 类型注释：如何书写和获取类型注释、使用typing模块

块注释和行内注释

都以#开头（一般还要在#之后加一个空格），#一直到行末都是注释范围

# 块注释一般用于描述下方代码
if a > 10 :
    # 按照PEP8规范，块注释以一个#和一个空格开头，除非块注释中需要使用缩进
    a = 10
else:
    # 块注释应该和它要注释的代码具有同样的缩进
    a *= 2

# 行内注释用于注释一行代码
a //= 2             # 很难想象一行代码有什么需要注释的，所以大多数时候它是无用的
b **= 2             # 不要注释这种显而易见的代码
c = {
   word : annotation for word, annotation in dictionary if len(annotation) > 1}  # 注释这样比较复杂的代码

块注释和行内注释是最简单、最常见的注释，它们在其他语言中也非常普遍

文档注释

文档注释是可以用于模块、函数、类、方法的注释，由成对的六个个单引号或双引号组成（最好用双引号）

模块

模块的文档注释放在文件开头的标识和import之间

下方的"""this is a test module"""即是模块文档注释

module1.py

#!/usr/bin/env python3
# -*- coding:utf-8 -*-

"""this is a test module"""

import requests
from lxml import etree

# TODO: code here

---

其实文档开头的

#!/usr/bin/env python3
# -*- coding:utf-8 -*-

也可以算一种注释，不过这种注释不（只）是给人看的，它标识了运行文件的程序和编码

函数

函数文档注释放在def的下一行，且必须要在函数的代码主体之前

这个是python内置的max函数的文档注释，可以看到它写了函数的参数、返回值和简要说明

module1.py

# 多行函数文档注释
def max(*args, key=None): # known special case of max
    """
    max(iterable, *[, default=obj, key=func]) -> value
    max(arg1, arg2, *args, *[, key=func]) -> value

    With a single iterable argument, return its biggest item. Th