Question

本书的这一部分谈的是用于编写Python代码的文档的技术和工具。尽管Python代码具有可读性，但在合适的地方放一些人们可读的注释，也能很大程度上帮助其他人了解你的程序所做的工作。Python包含了可以使文档的编写变得更简单的语法和工具。

虽然这是和工具相关的概念，但这个主题会在这里介绍有两个原因，一是它涉及了Python的语法模型，二是它是那些努力想了解Python工具集的读者的资源。就后面这个原因而言，我会在这里展开第4章第一次给出的对文档的介绍。就像往常一样，本章的结尾包括一些常见陷阱的提醒、本章习题，以及这一部分的练习题。

Python文档资源

本书已经介绍过，Python预置的功能数量惊人：内置函数和异常、预先定义的对象属性和方法、标准库模块等。此外，我们只谈到了这几种类型的皮毛而已。

通常困扰初学者的头几个问题之一是怎么找到这些内置工具的信息。本节提供了一些Python可用的文档资源。此外，还会介绍文档字符串（docstring）以及使用它们的PyDoc系统。这些话题对核心语言本身算是外围的话题。但是，一旦你编写代码的能力达到编写本书这一部分的例子和练习题的水平时，这就变成是重要的知识了。

如表15-1所示，可以从很多地方查找Python信息，而且一般都是信息量逐渐增加。因为文档是实际编程中重要的工具，我们会在接下来几节中探讨这些类型。

#注释

井字号注释是代码编写文档的最基本方式。Python会忽略#之后所有文字（只要#不是位于字符串常量中），所以你可以在这个字符之后插入一些对程序员有意义的文字和说明。不过，这类注释只能从源代码文件中看到。要编写能够更广泛的使用的注释，请使用文档字符串。

实际上，当前最佳的实践经验通常都表明，文档字符串最适于较大型功能的文档（例如，“我的文件做这些事”），而#注释最适用于较小功能的文档（例如，“这个奇怪的表达式做这些事”）。马上就会介绍文档字符串了。