註釋 —— Python教程

註釋能夠給代碼增長可讀性，在 Python 中支持單行註釋和多行註釋。本節教程中將講解 Python 如何添加註釋和使用的樣式。

編寫註釋是好的編程習慣。它在代碼中不會被執行，可是卻很重要。由於這能對讀代碼的人幫助很大，好比程序測試人員能夠參考註釋讓白盒測試變得更加容易。

添加註釋最好的方法是在程序建立和更新的開頭，由於這有助於關聯程序的上下文關係。

添加註釋

註釋是一種優先級很是高的表達式，帶標記的文本行，用來註釋一段代碼。在 Python 中有兩種註釋風格，分別是單行註釋和多行註釋。

單行註釋

在調試代碼添加註釋時，大多數會選擇單行註釋。單行註釋以井號（#）開頭，並自動以行末結尾。

# Good code is self-documenting.

print("Learn Python")
複製代碼

在寫註釋時，要確保註釋和下方的代碼有一樣的縮進，特別是在內部註釋代碼塊時要注意對齊。

# Define a list of months
months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']

# Function to print the calender months
def showCalender(months):
    # For Loop that traverses the list and prints the name of each month
    for month in months:
        print(month)

showCalender(months)
複製代碼

多行註釋

Python 容許跨行註釋，這種註釋稱爲多行註釋或塊註釋，能夠用來描述更復雜的內容。

使用井號（#）標記

多行註釋應該每行井號（#）開頭，後跟一個空格，這樣註釋就能夠分爲幾段。

# To Learn any language you must follow the below rules.
# 1. Know the basic syntax, data types, control structures and conditional statements.
# 2. Learn error handling and file I/O.
# 3. Read about advanced data structures.
# 4. Write functions and follow OOPs concepts.

def main():
    print("Let's start to learn Python.")
...
複製代碼

文檔字符串

Python 具備文檔字符串（docstring）功能。它爲每一個 Python 模塊、函數、類和方法快速添加註釋。只要在每一個對象（模塊、函數、類和方法）的第一個語句中定義字符串常量便可。

文檔字符串的範圍比 Python 註釋要廣不少。因此，它應該拿來描述函數是作什麼、不作什麼，等等。對於任何程序來講，添加文檔字符串是一個好習慣。

定義文檔字符串

能夠用三個引號（'''）來定義文檔字符串。在註釋的開頭和結尾各添加一個。就像多行註釋同樣，文檔字符串也能夠疊加成多行。

註釋和文檔字符串有什麼不一樣？

由於三引號開頭的字符串是常規字符串，因此是可被執行的語句。若是沒有特殊標記文檔字符串，那麼在代碼塊執行完成後將會進入垃圾回收。

Python 的解釋器不會像註釋同樣忽略文檔字符串。因此，若是將這樣的字符串放在函數和類定義以後或模塊頂部，那麼就會被 Python 解釋器認爲這段字符串是文檔字符串。

可使用 __doc__ 變量調用文檔字符串：

myobj.__doc__
複製代碼

例子：

def theFunction():
    ''' This function domaonstrate the use of docstring in Python. '''
    print("Python docstring are not comments.")

print("\nJust printing the docstring value...")
print(theFunction.__doc__)
複製代碼

小結

在程序中添加註釋和文檔字符串會讓代碼具備更好的可讀性和維護性。即便之後須要重構代碼，由於有註釋也會讓這個過程變得容易理解不少。

就像這句話說的同樣：

Software spends only 10% time of its life in development and rest of 90% in maintenance.

因此，在項目代碼中儘可能添加註釋和文檔字符串每每有助於未來的維護工做。