1.4 用文檔字符串注釋代碼

當(dāng)我們編寫的代碼可能被其他開發(fā)人員使用時，添加注釋是一個好習(xí)慣。注釋應(yīng)該包括如何使用代碼、代碼使用的前提條件，以及每個函數(shù)的作用。

Python使用文檔字符串（docstring）來注釋代碼。這些字符串用三引號（"""）定義，是其注釋的函數(shù)、類或模塊的第一條語句。

你可能已經(jīng)注意到，之前下載的Mechanics項目代碼是使用這些文檔字符串的方式。例如，matrix.py文件中Matrix類的方法被注釋如下：

如果在使用某段代碼時，你有一些疑問，則可以使用Python全局函數(shù)help。對模塊、函數(shù)、類或方法使用help函數(shù)，會返回對應(yīng)代碼的文檔字符串。例如，我們可以在Python解釋器控制臺中獲得set_data方法的注釋文件，命令如下：

一些自動化工具，如Sphinx（https://www.sphinx-doc.org/），可以將項目中的文檔字符串生成HTML、PDF或plaintext格式的文檔。你可以將這些文檔與代碼一起發(fā)布，這樣其他開發(fā)人員就可以很好地學(xué)習(xí)你所寫的代碼。

考慮到篇幅有限，我們在本書中不會寫文檔字符串，但是在你下載的代碼中都有，你可以去那里查看。