Python類和方法注釋規(guī)范說明

更新時間：2022年06月10日 11:01:49 作者：XerCis

這篇文章主要介紹了Python類和方法注釋規(guī)范說明，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教

Python類和方法注釋規(guī)范

這里寫圖片描述

注釋風格

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

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可快速查看注釋

代碼規(guī)范（含代碼注釋）

代碼縮進和冒號

注意條件語句必須嚴格控制縮進，保證父句和子句的關(guān)系

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

空行分隔代碼段

例如if語句判斷、while循環(huán)、for循環(huán)、def函數(shù)、class類等代碼段前后最好留一行（人工分好段落）

# if語句
if num>5:
? ? print('yes')
else:
? ? print('no')
?
# for循環(huán)
for i in (1,2,4):
? ? print(i)
?
# while循環(huán)
while i>3:
? ? print('yes')
? ? i+=1
else:
? ? print('end')
? ??
# 函數(shù)定義
def show():
? ? print(132)
?
# 類定義
class Person:
? ? def show(self):
? ? ? ? print(123)