Python类和方法注释规范

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文档