# DocStrings
Python有一個很奇妙的特性,稱為 文檔字符串 ,它通常被簡稱為 docstrings 。DocStrings是一個重要的工具,由于它幫助你的程序文檔更加簡單易懂,你應該盡量使用它。你甚至可以在程序運行的時候,從函數恢復文檔字符串!
```
#!/usr/bin/python
# Filename: func_doc.py
def printMax(x, y):
????'''Prints the maximum of two numbers.
????The two values must be integers.'''
????x = int(x) # convert to integers, if possible
????y = int(y)
????if x > y:
????????print x, 'is maximum'
????else:
????????print y, 'is maximum'
printMax(3, 5)
print printMax.__doc__
```
(源文件:[code/func_doc.py](code/func_doc.py))
## 輸出
```
$ python func_doc.py
5 is maximum
Prints the maximum of two numbers.
????????The two values must be integers.
```
## 它如何工作
在函數的第一個邏輯行的字符串是這個函數的 文檔字符串 。注意,DocStrings也適用于[模塊](ch08.html)和[類](ch11.html),我們會在后面相應的章節學習它們。
文檔字符串的慣例是一個多行字符串,它的首行以大寫字母開始,句號結尾。第二行是空行,從第三行開始是詳細的描述。 強烈建議 你在你的函數中使用文檔字符串時遵循這個慣例。
你可以使用`__doc__`(注意雙下劃線)調用`printMax`函數的文檔字符串屬性(屬于函數的名稱)。請記住Python把 每一樣東西 都作為對象,包括這個函數。我們會在后面的[類](ch11.html)一章學習更多關于對象的知識。
如果你已經在Python中使用過`help()`,那么你已經看到過DocStings的使用了!它所做的只是抓取函數的`__doc__`屬性,然后整潔地展示給你。你可以對上面這個函數嘗試一下——只是在你的程序中包括`help(printMax)`。記住按**q**退出`help`。
自動化工具也可以以同樣的方式從你的程序中提取文檔。因此,我 強烈建議 你對你所寫的任何正式函數編寫文檔字符串。隨你的Python發行版附帶的**pydoc**命令,與`help()`類似地使用DocStrings。
- 版權信息
- 前言
- 本書的由來
- 本書目前的狀況
- 約定條款
- 反饋
- 值得思考的一些東西
- 第1章 介紹
- Python的特色
- 為什么不使用Perl?
- 程序員的話
- 第2章 安裝Python
- Windows?用戶
- 概括
- 第3章 最初的步驟
- 使用帶提示符的解釋器
- 挑選一個編輯器
- 使用源文件
- 可執行的Python程序
- 獲取幫助
- 概括
- 第4章 基本概念
- 數
- 字符串
- 變量
- 標識符的命名
- 數據類型
- 對象
- 邏輯行與物理行
- 縮進
- 概括
- 第5章 運算符與表達式
- 運算符
- 運算符優先級
- 表達式
- 概括
- 第6章 控制流
- if語句
- while語句
- for循環
- break語句
- continue語句
- 概括
- 第7章 函數
- 函數形參
- 局部變量
- 默認參數值
- 關鍵參數
- return語句
- DocStrings
- 概括
- 第8章 模塊
- 字節編譯的.pyc文件
- from..import語句
- 模塊的name
- 制造你自己的模塊
- dir()函數
- 概括
- 第9章 數據結構
- 列表
- 元組
- 字典
- 序列
- 參考
- 更多字符串的內容
- 概括
- 第10章 解決問題——編寫一個Python腳本
- 解決方案
- 軟件開發過程
- 概括
- 第11章 面向對象的編程
- self
- 類
- 對象的方法
- __init__方法
- 類與對象的方法
- 繼承
- 概括
- 第12章 輸入/輸出
- 儲存器
- 概括
- 第13章 異常
- try..except
- 引發異常
- try..finally
- 概括
- 第14章 Python標準庫
- sys模塊
- os模塊
- 概括
- 第15章 更多Python的內容
- 單語句塊
- 列表綜合
- 在函數中接收元組和列表
- lambda形式
- exec和eval語句
- assert語句
- repr函數
- 概括
- 第16章 接下來學習什么?
- 探索更多內容
- 概括
- 附錄A 自由/開放源碼軟件(FLOSS)
- 附錄B 關于本書
- 關于作者
- 關于譯者
- 關于簡體中文譯本
- 附錄C 修訂記錄
- 術語表