Python应用开发指南

第4章　代码文档和最佳实践

到目前为止，我们的重点是代码的开发并进行了第一次发布。我们还没有谈到应用开发的另一个重要方面——文档和编码标准。虽然代码库仍然很容易管理，但还好现在还不算太晚，我们应该学习提高代码可读性的技术。在本章中，我们将介绍以下主题：

• 理解reStructuredText格式的基础知识，以及如何使用它书写文档字符串。
• 学习如何使用Sphinx文档生成器为代码创建HTML文档。
• 包括一些重要的Python编码标准。
• 使用Pylint评估我们按照规范编码的规范程度。

正如你可以从前面的主题猜测到的那样，我们先暂停一下代码的编写，来学习这些非常重要的概念，如图4-1所示。

图4-1

如果你对代码非常了解，那么可能会发现文档是不必要的。但想象一下：你被分配了一个不同的项目，有大量的代码，但是只有很少的文档。你会有什么感觉？当然，无论如何你都得审查代码以熟悉它。但如果没有得到很好的说明文档，你的生产力将会受到严重的影响。你花在理解代码上的时间也取决于代码写得有多好。这就是编码规范引起人们注意的主要原因。

总之，不要忽视编码标准和文档。当开发代码时，请确保遵循这些准则。维护文档也同样重要，但是也不要过度文档化。让我们从学习为Python项目创建良好文档的技术开始。

4.1　编写代码文档

大体上，有三个层次的文档。在最外层，可能有项目级别或者发行版级别的文档。它的目的是提供项目的高层次信息，如安装说明、许可条款等。在第3章中，已经有了一点这种文档的意味了。我们创建了随发行版一起发布的README和LICENSE文件。此外，你可以添加更多的说明文档，如 ...