Python类和方法注释规范

注释风格

1. reStructuredText（PyCharm默认）

def func(path, field_storage, temporary):    '''基本描述    详细描述    :param path: The path of the file to wrap    :type path: str    :param field_storage: The :class:`FileStorage` instance to wrap    :type field_storage: FileStorage    :param temporary: Whether or not to delete the file when the File instance is destructed    :type temporary: bool    :returns: A buffered writable file descriptor    :rtype: BufferedFileStorage    '''    pass

2. NumPy

def func(path, field_storage, temporary):    '''基本描述    详细描述    Parameters    ----------    path : str        The path of the file to wrap    field_storage : FileStorage        The :class:`FileStorage` instance to wrap    temporary : bool        Whether or not to delete the file when the File instance is destructed    Returns    -------    BufferedFileStorage        A buffered writable file descriptor    '''    pass

3. Google（官方推荐）

def func(path, field_storage, temporary):    '''基本描述    详细描述    Args:        path (str): The path of the file to wrap        field_storage (FileStorage): The :class:`FileStorage` instance to wrap        temporary (bool): Whether or not to delete the file when the File instance is destructed    Returns:        BufferedFileStorage: A buffered writable file descriptor    '''    pass

风格	特点	适用
reStructuredText	用冒号分隔	PyCharm默认
NumPy	用下划线分隔	倾向垂直，长而深的文档
Google	用缩进分隔	倾向水平，短而简单的文档

Sphinx对NumPy和Google风格的对比，英文不好可以参考中文版

小技巧

在PyCharm中Ctrl+Q可快速查看注释

参考文献

1. Python风格规范 — Google 开源项目风格指南
2. Sphinx入门——快速生成Python文档