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=f