Python类和方法注释规范
注释风格
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
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
- 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 | 用下划线分隔 | 倾向垂直,长而深的文档 |
用缩进分隔 | 倾向水平,短而简单的文档 |
Sphinx对NumPy和Google风格的对比,英文不好可以参考中文版
小技巧
在PyCharm中Ctrl+Q
可快速查看注释