Python類和方法註釋規範說明

2022-06-10 14:02:22

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

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

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可快速檢視註釋

程式碼規範（含程式碼註釋）

程式碼縮排和冒號

注意條件語句必須嚴格控制縮排，保證父句和子句的關係

num = 10
if num>5:
    print('yes')
else:
    print('no')

空行分隔程式碼段

例如if語句判斷、while迴圈、for迴圈、def函數、class類等程式碼段前後最好留一行（人工分好段落）

# if語句
if num>5:
    print('yes')
else:
    print('no')
 
# for迴圈
for i in (1,2,4):
    print(i)
 
# while迴圈
while i>3:
    print('yes')
    i+=1
else:
    print('end')
    
# 函數定義
def show():
    print(132)
 
# 類定義
class Person:
    def show(self):
        print(123)