<< >>

diveintopython.org |

Python for experienced programmers

## 1.3. 文档化函数

可以通过给出一个文档字符串文档化一个Python函数。

例 1.4. 定义 `buildConnectionString` 函数的文档字符串

    def buildConnectionString(params):
        """Build a connection string from a dictionary of parameters.

        Returns string."""

三重双引号的引用表示一个多行字符串。在定义一个文档字符串的时候，你会看到它们经常被使用。

任何在三重双引号中的东西都是函数的文档字符串，它们用来说明函数可以做什么。如果存在文档字符串，它必须要在函数中的被首先定义(也就是说在冒号后面被定义)。在技术上不需要给函数定义文档字符串，但是你应该这样做。我相信在你所参加过的每一个编程课上已经听到过这一点，但是Python会给你一些其它的机制：文档字符串在运行时可作为函数的属性。

许多Python IDE使用文档字符串来提供上下文相关提示，这样当你敲入一个函数名，它的文档字符串将显示为提示框。这一点相当的有用，但是完全要看你写的文档字符串的好坏了。

进一步阅读 |

- Python Style Guide 讨论了如何写出好的文档字符串。
- Python Tutorial 讨论了对于文档字符串中的空白的习惯。

« 声明函数 | 每个都是对象 »