python通用规范-2

文章目录

2.1 类、接口和函数
2.1.1 类和接口的注释写在类声明(class ClassName:)所在行的下一行，并向后缩进4个空格
2.1.2 公共函数的注释写在函数声明(`def FunctionName(self):`)所在行的下一行，并向后缩进4个空格
2.2 属性
2.2.1 公共属性的注释写在属性声明的上方，与声明保持同样的缩进。行内注释应以`#`和一个空格作为开始，与后面的文字注释以一个空格隔开
2.3 格式
2.3.1 模块注释写在文件的顶部，导入(`import`)部分之前的位置，不需要缩进
2.3.2 文档字符串多于一行时，末尾的`"""`要自成一行
2.3.3 注释必须与其描述的代码保持同样的缩进，并放在其上方相邻位置
2.4 建议
2.4.1 源程序有效注释量（包括DocString）应该在20％以上
2.4.2 注释的内容要清楚，防止注释二义性
2.4.3 避免在注释中使用缩写
2.4.4 保持代码和注释的同步修改
1.2.4.5 有含义的变量应该加上注释
2.4.6 全局变量要有较详细的注释
2.1 类、接口和函数

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

说明：功能描述除了描述类或接口功能外，还要写明与其他类或接口之间的关系；属性清单列出该类或接口的接口方法的描述；修改记录包括修改人，修改日期及修改内容。
正确示例：
class TreeError(libxmlError):
"""
功能描述：
接口：
修改记录：
"""
1
2
3
4
5
6
7
2.1.2 公共函数的注释写在函数声明(def FunctionName(self):)所在行的下一行，并向后缩进4个空格

说明：公共函数注释的内容包括功能描述、输入参数、输出参数、返回值、调用关系（函数、表）、异常描述，修改记录等。异常描述必须说明异常的含义及什么条件下抛出该异常，除描述函数内部抛出的异常外。
# 正确示例：
def load_batch(fpath):
"""
功能描述：
参数：
返回值：
异常描述：
修改记录
"""
1
2
3
4
5
6
7
8
9
2.2 属性

2.2.1 公共属性的注释写在属性声明的上方，与声明保持同样的缩进。行内注释应以#和一个空格作为开始，与后面的文字注释以一个空格隔开

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

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

# 正确示例：
# Compensate for border
x = x + 1
1
2
3
4
5
6
7
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
"""
1
2
3
4
5
6
7
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."""
1
2
3
4
5
6
7
8
9
10
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 is not None:
# Deletes the image if it is in queued or saving state
self._delete_image(context, image_meta['id'], image_service)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
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
1
2
3
4
5
6
7
2.4.6 全局变量要有较详细的注释

说明：全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过程修改它以及存取时注意事项等的说明。
————————————————
版权声明：本文为CSDN博主「zhao12501」的原创文章，遵循CC 4.0 BY-SA版权协议，转载请附上原文出处链接及本声明。
原文链接：https://blog.csdn.net/zhao12501/article/details/115455082