注释规范包括文件注释、文档注释、代码注释和TODO注释。这里需要强调一点即在程序代码中对容易引起误解的代码进行注释是必要的但应避免对已经清晰表达信息的代码进行再次注释因为频繁的注释有时恰恰反映了代码的低质量当觉得被迫需要添加注释的时候不妨考虑一下重写代码使其更加清晰。4.2.1 文件注释文件注释就是在每一个文件的开头处所添加的注释。文件注释采用多行注释需要注意的是文件注释不会生成API帮助文档。文件注释通常包括如下信息版权信息、文件名、所在模块、作者信息、历史版本信息、文件内容和作用等。示例代码如下# 资源包\Code\chapter4\4.2\0401.py # 版权所有 2012 来自远方的老作者 # 许可信息查看LICENSE.txt文件 # 描述: # 实现日期基本功能 # 历史版本 # 2017-7-22: 创建 来自远方的老作者 # 2017-8-20: 添加datetime模块 # 2017-8-22: 添加math模块4.2.2 文档注释文档注释就是文档字符串其注释内容能够生成API帮助文档。这里需要注意的是所有公有的模块、函数、类和方法都应该进行文档注释。文档注释推荐使用一对三重双引号包裹起来而不推荐使用三重单引号。示例代码如下# 资源包\Code\chapter4\4.2\0402.py class Login(object): 类的作用说明例如此类用来写登录 def __init__(self): 初始化你要的参数说明 pass def check(self): 你要实现的功能说明 pass此外在Python中可以通过使用Python官方提供的pydoc工具和内置函数help()查看文档注释。1使用pydoc工具查看文档注释。首先打开命令提示符然后进入当前文件所在的位置输入“python –m pydoc 0402”即可实现在控制台中查看文档注释如图4-1所示。图4-1 控制台中查看文档注释此外输入“python –m pydoc –w 0402”即可生成HTML文件如图4-2所示。图4-2 生成HTML文件2使用内置函数help()查看文档注释其示例代码如下# 资源包\Code\chapter4\4.2\0403.py class Login(object): 类的作用说明例如此类用来写登录 def __init__(self): 初始化你要的参数说明 pass def check(self): 你要实现的功能说明 pass help(Login)上述代码的运行结果如图4-3所示。图4-3 使用内置函数help()查看文档注释4.2.3 代码注释可以通过使用#为单行代码添加注释代码注释建议加在代码的右侧或者上方。示例代码如下# 资源包\Code\chapter4\4.2\0404.py # 定义变量代表教师 teacher 来自远方的老作者4.2.4 TODO注释在编写程序时有些代码的功能暂时无法确定或者暂时未完成为了便于后期查找可以使用TODO注释。示例代码如下# 资源包\Code\chapter4\4.2\0405.py name 来自远方的老作者 age 35 teach Python def teacher(name, age, teach): return f老师的名字{name}老师的年龄{age}老师所教的课程{teach} # TODO 待完成功能调用函数teacher