编写Python开发文档的重要性

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

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

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

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

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

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

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

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