Python代碼的文檔的技術和工具。儘管Python代碼具有很高的可讀性,在合適的地方當時幫助文檔或者註釋,能很大程度的幫助別人瞭解你的程序工作內容。
註釋
與其他代碼一樣,Python的註釋以#號開頭,主要用來表示某句話,某個語句主要是用來做什麼。
dir函數
內置的dir函數可以查看某個對象內所有可用屬性的列表。
>>> dir(list) #查看list對象中可用的屬性和方法
['__add__', '__class__', '__contains__', '__delattr__', '__delitem__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__getitem__', '__gt__', '__hash__', '__iadd__', '__imul__', '__init__', '__iter__', '__le__', '__len__', '__lt__', '__mul__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__reversed__', '__rmul__', '__setattr__', '__setitem__', '__sizeof__', '__str__', '__subclasshook__', 'append', 'clear', 'copy', 'count', 'extend', 'index', 'insert', 'pop', 'remove', 'reverse', 'sort']
>>>
文檔字符串__doc__
這類文檔一般寫在模塊文件、對象或者函數的最前端,使用三引號構成的字符串,Python會自動封裝這些字符串,形成所謂的文檔字符串,這些字符串是介紹改代碼的主要功能的幫助文檔:
>>> def document():
... #這裏加上註釋也是沒有關係的,要保證文檔字符串在所有可執行代碼的最前端。
... '''hello
... my name is baymax.
... enjoy Python'''
... print("hello world")
...
>>> document()
hello world
>>> document.__doc__
'hello \n my name is baymax.\n enjoy Python'
>>> help(document)
Help on function document in module __main__: #這一行的信息顯示是函數文檔,在__main__模塊中。
document()
hello
my name is baymax.
enjoy Python
>>>
Python中並沒有對文檔字符串的明確標準。但是強烈建議在自己寫的模塊和代碼中加入適當的說明。Python的內置模塊和對象都使用類似的技術。
PyDoc:help函數
標註的PyDoc工具是Python程序代碼,它知道如何提取文檔字符串並自動提取其結構化的信息。並將其格式化成各種類型的排列友好的報表。最主要的PyDoc接口是內置的help函數和PyDoc GUI/HTML接口。help函數會啓用PyDoc從而產生簡單的文字報表。
Python:HTML報表
PyDoc也提高GUI接口,可以將報表通過HTML網頁格式來呈現。可以通過任何網頁瀏覽器來查看,PyDoc會收集代碼中各個文件中文檔字符串,並在網頁上顯示出來。
網絡資源
也可以從Python官網上下載,Python的標準手冊集。在各個Python論壇中學習Python,在官網上發佈信息瞭解最新版的Python。對於一些出版的書籍可能會滯後於Python新版本的發佈。
常見編寫代碼陷阱
- 別忘了冒號,在複合語句的首行,一般都是以冒號結尾
- 從頂格開始寫,確保Python的頂層嵌套是沒有任何代碼縮進的
- 空白行在交互模式提示符下很重要
- 縮進要一致,同一層的代碼塊要保持一致的縮進量。
- 不要在Python中寫C代碼,比如條件判斷不用打括號
- 使用簡單的for循環,而不是使用while或者range:對於相同的循環邏輯,簡單的for循環總是容易寫,運行起來也更快。
- 要注意賦值語句中的可變對象。要分清Python中的可變對象和不可變對象。
- 不要期待在原處修改對象的函數會返回結果。如list.append(object)
- 在調用函數時,一定要用括號。必須在使用函數時加上括號,無論它是否需要傳遞參數。
- 不要在使用和導入模塊時,帶上多餘的擴展名。