注释规范
不使用 "'''
" 书写注释块
不要使用三引号去注释代码。 这不是好的实践,因为面向行的命令行工具,比如说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