Python通用编程规范-02注释

文章目录

2.1 类、接口和函数

2.1.1 类和接口的注释写在类声明(class ClassName:)所在行的下一行，并向后缩进4个空格

说明：功能描述除了描述类或接口功能外，还要写明与其他类或接口之间的关系；属性清单列出该类或接口的接口方法的描述；修改记录包括修改人，修改日期及修改内容。

正确示例：
classTreeError(libxmlError):"""
    功能描述：
    接口：
    修改记录：
    """

2.1.2 公共函数的注释写在函数声明(

def FunctionName(self):

)所在行的下一行，并向后缩进4个空格

说明：公共函数注释的内容包括功能描述、输入参数、输出参数、返回值、调用关系（函数、表）、异常描述，修改记录等。异常描述必须说明异常的含义及什么条件下抛出该异常，除描述函数内部抛出的异常外。

# 正确示例：defload_batch(fpath):"""
    功能描述：
    参数：
    返回值：
    异常描述：
    修改记录
    """

2.2 属性

2.2.1 公共属性的注释写在属性声明的上方，与声明保持同样的缩进。行内注释应以

#

和一个空格作为开始，与后面的文字注释以一个空格隔开

说明：行内注释的形式是在语句的上一行中加注释。行内注释要少用。它们应以#和一个空格作为开始。

# 错误示例：#Compensate for border
x = x +1# 正确示例：# Compensate for border
x = x +1

2.3 格式

2.3.1 模块注释写在文件的顶部，导入(

import

)部分之前的位置，不需要缩进

说明：每次模块代码修改后要写明修改信息，修改信息包括修改人，修改日期及修改内容。

# 正确示例："""
功 能：XXX类，该类主要涉及XXX功能
版权信息：华为技术有限公司，版本所有(C) 2010-2017
修改记录：2015-3-17 12:00 XXX XXXXXXXX 创建
2017-3-17 12:00 XXX XXXXXXXX 修改 XXX
"""

2.3.2 文档字符串多于一行时，末尾的

"""

要自成一行

说明：对于只有一行的文档字符串，把

"""

放到同一行也没问题。单行可以放同一行。

错误示例：
"""Return a foobang
Optional plotz says to frobnicate the bizbaz first."""

正确示例：
"""Return a foobang
Optional plotz says to frobnicate the bizbaz first.
"""
正确示例：
"""API for interacting with the volume manager."""

2.3.3 注释必须与其描述的代码保持同样的缩进，并放在其上方相邻位置

说明：注释应与其描述的代码相近，并与所描述的代码保持同样的缩进。对代码的注释应放在其上方相邻位置，不可放在下面。

# 错误示例：注释与所描述的代码有不同的缩进# get replicate sub system index and net indicator
repssn_ind = ssn_data[index].repssn_index
repssn_ni = ssn_data[index].ni

# 正确示例：# get replicate sub system index and net indicator
repssn_ind = ssn_data[index].repssn_index
repssn_ni = ssn_data[index].ni

# 正确示例：if image_service isnotNone:# Deletes the image if it is in queued or saving state
    self._delete_image(context, image_meta['id'], image_service)

2.4 建议

2.4.1 源程序有效注释量（包括DocString）应该在20％以上

说明：注释的原则是有助于对程序的阅读理解，没有类型信息，IDE不能帮助提示，如果没有注释，动态语言就很难理解，注释不宜太多也不能太少，注释描述必须准确、易懂、简洁。

2.4.2 注释的内容要清楚，防止注释二义性

说明：错误的注释不但无益反而有害。注释的要点是准确，没有二义性。把代码说清楚是目的。

2.4.3 避免在注释中使用缩写

说明：在使用缩写时或之前，应对缩写进行必要的说明。

2.4.4 保持代码和注释的同步修改

说明：边写代码边注释，修改代码时始终优先更新相应的注释，以保证注释与代码的一致性。不再有用的注释要删除。

1.2.4.5 有含义的变量应该加上注释

说明：对于有物理含义的变量，如果其命名不是充分自注释的，在声明时必须加以注释，说明其物理含义。变量的注释应放在其上方相邻位置。

# 错误示例：# 没有注释
_MAX_ACT_TASK_NUMBER =1000# 正确示例：# maximum number of active statistic tasks
_MAX_ACT_TASK_NUMBER =1000

2.4.6 全局变量要有较详细的注释

说明：全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过程修改它以及存取时注意事项等的说明。