注释规范
不使用 "'''" 书写注释块
不要使用三引号去注释代码。 这不是好的实践，因为面向行的命令行工具，比如说grep，不会知道注释过的代码是没有激活的。对每一个注释行，使用带有合适缩进的井号会更好。您的编辑器可能很容易做到这一点，并能切换注释/取消注释。
常见的注释风格
java程序员都知道 javadoc 这个工具，可以根据注释生成文档。python本身并不包含这样的工具，但python有一个非常著名的工具 sphinx， 该工具提供了类似于 javadoc 的功能，程序员可以使用reStructuredText文本标记语言编写文档，然后将文档编译生成html/pdf/epub等格式。
sphinx 工具生成的手册大多数程序员都见过，例如python的官方手册，你可以在网页右下角看到 sphinx 的技术支持说明。
程序员常用的 readthedoc 也主要使用sphinx来生成文档。另一个类似的工具是gitbook；经常有程序员会拿 readthedoc 和 gitbook 比较，笔者认为前者更适合用于编写技术手册、开发手册，而后者则更适合用于写书。如今IT行业的技术手册，使用 reStructuredText+sphinx+readthedoc 方式几乎是一种共识。
sphinx 提供了 autodoc 的插件，可以导入一个模块，根据docstring生成用户手册。所以，python的docstring注释会使用 reStructuredText 作为文本标记语言，生成文档的时候都是带有“格式”的，并且不同风格的docstring均会“扩展”一些语法，在最终使用sphinx生成手册的时候需要一些sphinx插件用于解析扩展的语法，下文的docstring格式示例会看到这一点。
常见的python程序注释风格有3种：
- google推荐的注释风格，支持模块、类、函数、变量注释，非常详细，且易于阅读。
- numpy风格的注释，支持模块模块、类、函数、变量注释，同样易于阅读。
- sphinx风格的注释，支持函数、类，通过sphinx格式化输出比较漂亮，但阅读性弱一些。
reStructuredText
核心语法
:param <类属性名称>: <描述>
:type <类属性名称>: <类型>
:return: <对返回值的描述>
:rtype: <返回值类型>
:raises: <可能抛出的异常列表>
class ReadClass:
"""阅读类
"""
def __init__(self,read:bool=True):
"""阅读类初始化
阅读权限
:param read: 阅读权限
:type read: bool
"""
self.read = read
def read_csv(self, path: str = "", header: int = 0, use_cols: list = None) -> DataFrame:
"""读取csv
可以选择参数的读取csv
:param path: 路径
:type path: str
:param header: 是否读第一行为列名
:type path: str
:param use_cols: 读的目标列
:type path: str
:return: 数据框
:rtype: DataFrame
"""
if self.read:
if use_cols is None:
use_cols = ['date']
df = pd.read_csv(path, header=header, usecols=use_cols)
else:
df = pd.DataFrame()
return df
Numpy style
def random_number_generator（arg1，arg2）：
"""
摘要行。
扩展功能描述。
参数
----------
arg1：int
arg1的描述
arg2：str
arg2的描述
返回
-------
int
返回值说明
"""
return 42
Google风格
class ReadClass:
"""阅读类
"""
def __init__(self, read: bool = True):
"""阅读类初始化
阅读权限
Args:
read(bool): 阅读权限
"""
self.read = read
def read_csv(self, path: str = "", header: int = 0, use_cols: list = None) -> DataFrame:
"""读取csv
可以选择参数的读取csv
Args:
path(str): 路径
header(int): 是否读第一行为列名
use_cols(list): 读的目标列
Returns:
DataFrame: 数据框
"""
if self.read:
if use_cols is None:
use_cols = ['date']
df = pd.read_csv(path, header=header, usecols=use_cols)
else:
df = pd.DataFrame()
return df