文件字串 (documentation string) 定義在模組 (module) 、函數 (function) 、類別 (class) 及方法 (method) 中，用為程式的說明文件，可用預設屬性 (attribute) __doc__ 存取
說明文件不外是解釋程式某部分的使用方式，通常會舉出簡單的例子，傳統程式語言 (programming language) 的說明文件大都是額外編寫，印成紙書或放在網路供人查詢，或是以註解 (comment) 形式加進原始程式碼 (source code) 中， Python 文件字串的特點讓程式設計師可以邊寫程式邊查文件，無須翻紙書或查網路。
我們先進入 Python 的互動式介面來看看吧！下面印出內建函數 int() 的屬性 __doc__
int() 用來建立整數物件 (object) ，因此回傳一個整數物件，這裡可以看到 int() 的解釋與用法。
下面再來看看串列 (list) 的文件字串
串列的文件字串只有簡單印出用法，大體上文件字串是依需要來設置。文件字串分成兩種，一種是單行的文件字串，另一種則是多行，下面我們用單元 8 的 big() 函數示範單行文件字串的寫法
| def big(a, b): | |
| """Return the bigger argument.""" | |
| if a > b: | |
| return a | |
| else: | |
| return b |
文件字串採用三個引號，也就是字串前後都用三個引號圍起來，單行的文件字串就是簡單的寫明函數用途
| """Return the bigger argument.""" |
多行的文件字串同樣用三引號字串 (triple-quoted string) ，如下例
| def big(a, b): | |
| """Return the bigger argument. | |
| Args: | |
| a - the first one. | |
| b - the second one. | |
| """ | |
| if a > b: | |
| return a | |
| else: | |
| return b |
第一行同樣是函數用途，之後空一行，下面才是進一步的解釋說明，此例解釋參數 (parameter) 的用途。有沒有發現三引號字串是可以跨行的呢？是的，三引號字串可以跨行，因為三引號字串的主要用途就是當作文件字串，文件字串通常是多行的敘述。
下面我們替 class_dmeo9.py 加進模組、類別與方法的文件字串
| 001 | """An example of the Demo class. |
| 002 | |
| 003 | It demonstrates the docstring. |
| 004 | """ |
| 005 | |
| 006 | # This is a comment of a class. |
| 007 | class Demo: |
| 008 | """A docsting of the class.""" |
| 009 | # This is a comment of the method. |
| 010 | def __init__(self, v1=11, v2=22): |
| 011 | """A docsting of the __init__.""" |
| 012 | self.__a = v1 |
| 013 | self.__b = v2 |
| 014 | |
| 015 | # This is a comment of a method. |
| 016 | def do_something(self): |
| 017 | """A docsting of a method.""" |
| 018 | return self.__a + self.__b |
| 019 | |
| 020 | if __name__ == "__main__": |
| 021 | d = Demo(12, 34) |
| 022 | print(d.do_something()) |
| 023 | |
| 024 | # 檔名: class_demo10.py |
| 025 | # 作者: Kaiching Chang |
| 026 | # 時間: July, 2014 |
這裡僅作示範用，因此文件字串中都採取簡單的文字。
我們可以看到模組的文件字串出現在檔案的最開始，類別、方法或函數的文件字串都在關鍵字 (keyword) 的下一行，至於註解則在關鍵字的上一行，除了文件字串的位置須固定外，註解的位置是 Python 社群的習慣寫法，如果要對整個類別、方法或函數做註解，通常都會寫在關鍵字的上一行。
由於文件字串是用途及簡單例子，所以註解內容不應該與文件字串相同或相似，基本上註解的目的主要是對程式碼額外說明，至於說明內容依需要而定。
倒是不管文件字串或是註解都應按照開發團隊的習慣來走，我們這裡介紹的是官網 PEP 8 及 PEP 257 所建議的寫法。
接下來我們開發軟體的方式，帶領讀者開發 GUI 的編密碼軟體，藉此介紹更多的 Python 特性囉！
中英文術語對照
| 文件字串 | documentation string |
| 模組 | module |
| 函數 | function |
| 類別 | class |
| 方法 | method |
| 屬性 | attribute |
| 程式語言 | programming language |
| 註解 | comment |
| 原始程式碼 | source code |
| 物件 | object |
| 串列 | list |
| 三引號字串 | triple-quoted string |
| 參數 | parameter |
| 關鍵字 | keyword |
重點整理
- 文件字串用以說明模組、函數、類別及方法的功能，可用預設屬性 __doc__ 存取。
- 定義文件字串採用可以跨行的三引號字串，放在模組的開頭或 class 、 def 的下方第一行。
問題與討論
- 文件字串是什麼？為什麼要在程式中設置文件字串？
- 什麼是三引號字串？這跟字串有什麼不同？
練習
- 寫一個程式 exercise1301.py ，替 exercise1201.py 加入文件字串。
- 寫一個程式 exercise1302.py ，替 exercise1202.py 加入文件字串。
- 寫一個程式 exercise1303.py ，替 exercise1203.py 加入文件字串。
the end
沒有留言:
張貼留言