第4章 编码规范-4.2 注释规范

注释规范包括文件注释、文档注释、代码注释和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