编写Python开发文档的重要性

为自己的代码做的最重要一件事，就是告诉别人如何使用它，这有可能像只需要说明一点稍微复杂的逻辑那样简单，也有可能像编写 3000 行长的程序介绍那么复杂。我们把这些说明叫做文档。

文档既可能是说明如何使用程序的文件，也可能会内嵌在代码中，它可以包含示例项目、教程或者每个函数的清单。编写文档看上去像是一项占用了编写代码的时间的活动，然而，这却是大多数程序员必须要做的工作。

占用编写代码的时间难道不是一件糟糕的事吗？事实上，文档为每个参与者所节省的时间之多，常常令人难以置信。如果很好地为代码编写了文档，今后接手工作的所有程序员，都能更容易地搞明白代码是做什么的，以及他们可以如何使用代码，他们就能扩展代码来做更多的事情，或者修改所出现的 Bug。

不仅如此，文档在将来可能还会对自己有所帮助。今天看上去很直观的一些代码，明天可能就会令人很困惑。你可能真的忘记了为什么总是需要给出一个参数，或者为什么要用一个try/except子句把函数包围起来。

好的文档应该告诉用户想要使用一段代码所需要知道的信息，而且没有废话。试图介绍每种可能的状态或说明所编写的每行代码，会很容易把代码淹没在一个文档中。

过多的文档就像使用新数码相机那 320 页的用户手册一样。你可能不会痛下决心去阅读它。事实却是如此，你可能只会在使用遇到困难时才会从文档中寻找解决方案，但是并不会太在意自己可能错过了数百个其他功能。

好的文档应该是有组织的。其他的程序员会希望在特定的位置有某种特定类型的文档。关于函数能够做什么的说明，应该包含在函数中，并且通常要使用某种特定的格式。安装说明不应该在代码中，而应该位于一个单独的文件中。对于需要些技巧的代码的详细说明，应该在该代码的附近。

既然文档这么有用，那么应该如何编写呢？怎样才能编写出“高大上”的 Python 软件开发文档呢？请大家带着问题继续阅读《如何编写Python软件开发文档（7个技巧）》一节。