一、程式碼註釋介紹

• 註釋就是對程式碼的解釋和說明，其目的是讓人們能夠更加輕鬆地瞭解程式碼。
• 註釋是編寫程式時，寫程式的人給一個語句、程式段、函式等的解釋或提示，能提高程式程式碼的可讀性。
• 在有處理邏輯的程式碼中，源程式有效註釋量必須在20％以上。
  

二、程式碼註釋分類

行註釋：在符號後那一行不會被編譯（顯示）

塊註釋：被塊註釋符號中間的部分不會被編譯

三、python程式碼註釋基礎

Python中使用#表示單行註釋。單行註釋可以作為單獨的一行放在被註釋程式碼行之上，也可以放在語句或表示式之後。如下例子：

name = 'xiaohong' # 單行註釋

# 單行註釋

name = 'xiaohong'

Python中使用三個單引號或三個雙引號表示多行註釋。用在註釋多寫不下的情況，如下例子：

'''
這是使用三個單引號的多行註釋
'''

"""
這是使用三個雙引號的多行註釋
"""

四、DocStrings介紹與使用

4.1 DocStrings介紹

文件字串

是一個重要工具，用於解釋文件程式，幫助你的程式文件更加簡單易懂

4.2 python中使用DocStrings

在函式體的第一行使用一對三個單引號 ''' 或者一對三個雙引號 """ 來定義文件字串。你可以使用 doc（注意雙下劃線）呼叫函式中的文件字串屬性。

編寫示例如下：

def add(num1,num2):
  """ 完成傳入的兩個數之和

  :param num1: 加數1
  :param num2: 加數2
  :return: 和
  """
  return num1 + num2

print( add.__doc__ )

備註：DocStrings 文件字串使用慣例：它的首行簡述函式功能，第二行空行，第三行為函式的具體描述。

五、DocStrings常用編寫風格

5.1 reST風格

這是現在流行的一種風格，reST風格，Sphinx的御用格式，比較緊湊。

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

5.2 Google風格

"""
This is a groups style docs.

Parameters:
 param1 - this is the first param
 param2 - this is a second param

Returns:
 This is a description of what is returned

Raises:
 KeyError - raises an exception
"""

5.3 Numpydoc (Numpy風格)

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
 the 1st param name `first`
second :
 the 2nd param
third : {'value','other'},optional
 the 3rd param,by default 'value'

Returns
-------
string
 a value in a string

Raises
------
KeyError
 when a key error
OtherError
 when an other error
"""

六、一些註釋經驗

• 註釋不是越多越好。對於一目瞭然的程式碼，不需要添加註釋。
• 對於複雜的操作，應該在操作開始前寫上相應的註釋。
• 對於不是一目瞭然的程式碼，應該在程式碼之後添加註釋。
• 絕對不要描述程式碼。一般閱讀程式碼的人都瞭解Python的語法，只是不知道程式碼要幹什麼

以上就是本文的全部內容，希望對大家的學習有所幫助，也希望大家多多支援我們。