怎么写readme文档 README自述文件驱动软件开发

python部落(python.freelycode.com)组织翻译，禁止转载，欢迎转发。

这些天我听到了很多关于 TDD、BDD、极致编程、敏捷式软件开发、站立会议，以及各种各样的为开发出更好的软件而提出的方法和技术。但是我想说的是，除非你正在设计的软件能够符合使用要求，要不然这些都没什么用。换句话说，就算你的规范做的再好，没有用对地方就没有任何价值。同理，一个没有一本藏书的漂亮图书馆是没有任何价值的。如果你的软件解决了一个实际问题，但是没人知道怎么去用它，这样就没什么意义，问题依旧存在。

那我们如何解决这个问题呢？比你想象的要简单许多。

首先编写自述文件。

当然，我知道我们是程序员不是技术作家，但是为了编写一个好的软件，在你写任何代码、测试、计划、故事或者是任何其他的事情前，一份自述文件都是非常必要的。否则很有可能当你开始着手写软件的时候，你都不知道自己该如何写代码。在人们对瀑布式软件设计的强烈反对和对敏捷式软件开发的极力支持之间，我们一定缺失了什么东西。不要误解我的意思，瀑布式设计需要的东西太多了，以细微的细节来构造一个庞大的系统，最终会导致这些细微的细节构造出一个错误的系统。所以停止对瀑布式设计的使用是很明智的。但是换个思路想想，我们要拿什么来代替它？现在，我们有很多工程项目，它们只包含一个简单的或者一个随便写的文档，甚至可能都没有文档。有些工程项目甚至都没有自述文件。

这是并不能被接受，在有大量的技术规范和没有技术规范之间应该有个折中点。实际上，这个折中点是存在的，他就是自述文档。

区分自述文件驱动软件开发（RDD）和文档驱动软件开发（DDD）是很重要的。RDD 可以认为是 DDD 的一个子集或者一个微缩版。将设计文档简化为一个单个可读文件，然后作为软件的说明。RDD 通过限制文件内容的长度或者过于详细的说明文档来避免瀑布式开发的 DDD 弊端。同时 RDD 也鼓励是去实现库的小型化和模块化。这些简单的增强功能可以驱使你的项目朝着正确的方向前进，从而避免过多的、没必要的步骤。

先写自述文件，会给你带来一些好处：

• 最重要的一点是，它为你提供了一次全局审视项目的机会，从而避免了每次你改变了想法就去修改你的代码的麻烦。而这些想法可能是关于某些东西的应该如何组织，或者什么东西应该包含在公共 API 中。请记住那种感觉，那种你第一次编写自动化测试程序并且捕获到那些一不留神就可能溜进你代码中的错误的那种感觉。这种感觉就和你在实际编写代码前，先写自述文件的感觉一样。

• 编写自述文件还有另外一个好处，可以让你更好的了解你想实现什么。你将拥有一份非常好的文档。同时你会发现，当你的兴奋度和动机达到最高的时候，在项目开始前先写一份文档就会变的容易的多。当你的项目结束后你再去写自述文件将会变得很困难，并且你肯定会遗漏很多重要的细节。

• 如果你在一个团队中工作，你将会从你的自述文件中学习到更多的东西。如果在你完成这个项目之前，团队中的其他人可以看到这份文档，他们将会非常放心的使用你的代码接口来开展其他的项目工作。如果没有任何合适的预定义接口，你就不得不自己去写代码或者重写大部分的代码。

• 使用你写下的自述文件来参与讨论将会使事情变的简单。如果没有白纸黑字，人们很容易陷入对某个问题无休无止的讨论中。一个简答的办法就是把提议的解决方案写下来，这样大家进行反复讨论的时候就有一个具体的概念了。

把为你的项目写自述文件的过程看做一个真实的创作过程，在这里你可以表达你所有的想法。这份文件应该立足于你的观点，从而证明你的创造力和表达力。在你的代码库中，自述文件应该是一份最重要的文件，你应该首先写你的自述文件。

英文原文：http://tom.preston-werner.com/2010/08/23/readme-driven-development.html 译者：无,