[Python]编码规范性（三）——注释（类、接口、函数）

注释和文档字符串的原则是：有助于对程序的阅读理解；

python没有类型信息，IDE不能帮助提示，如果没有注释，动态语言就很难理解；

注释不宜太多也不能太少，一般建议建议有效注释量（包括文档字符串）应该在20%以上。 撰写好的注释有以下建议：

注释描述必须准确、易懂、简洁，不能有二义性；

避免在注释和文档字符串中使用缩写，如果要使用缩写则需要有必要的说明；

修改代码时始终优先更新相应的注释/文档字符串，以保证注释/文档字符串与代码的一致性；

有含义的变量，如果不能充分自注释，则需要添加必要的注释；

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

注释：

（必须遵守）（规则）：

1、类和接口的文档字符串写在类声明（class ClassName:）所在行的下一行，并向后缩进4个空格；

说明：

类和接口的文档字符串的内容可选择包括（但不限于）功能描述，接口清单等；

功能描述除了描述类或接口功能外，还要写明与其他类或接口之间的关系；

接口清单列出该类或接口的接口方法的描述；

class TreeError(libxmlError):
    """
    功能描述：
    接口：
    """

2、公共函数的文档字符串写在函数声明（def FunctionName(self):）所在行的下一行，并向后缩进4个空格；

说明：公共函数文档字符串的内容可选择包括（但不限于）功能描述、输入参数、输出参数、返回值、调用关系（函数、表）、异常描述等；

异常描述除描述函数内部抛出的异常外，还必须说明异常的含义及什么条件下抛出该异常；

def load_batch(fpath):
    """
    功能描述：
    参数：
    返回值：
    异常描述：
    """