在软件的文档中，有需求文档，设计文档（可能还分概要和详细设计），测试设计等等诸多文档。它们各有各的用途，本文就探讨下设计文档要不要写，写些什么的问题。

先设计再编码，还是直接编码。初入门的程序员，喜欢拿到需求后往往就开始写代码，写着写着要么写不下去，觉得走题了，要么觉得设计有问题，得推翻重来。当你经验丰富了以后，会先大致想好怎么做，然后把函数原型写好，最后再一个个函数实现出来。就像写文章，前者想到内容A就写内容A，想到B就写B，忽略了主线；而后者先做提纲，再提笔充实，避免了很多弯路。

所以，先设计再编码，在编码中完善设计，一般是大家都认同的。那么脑子中有提纲了，是否要用文档写下来呢？

写设计文档的过程，是帮助你深入理解需求，探求实现方式是否可行的过程。而且在写提纲的过程中，反复思考下，你常常会发现更优的实现方案。

好记忆不如烂笔头。过了很久之后，还记得某个问题怎么解决的吗？当时思路清晰，可现在都记不起了，还要具体地去翻代码吗？这里，如果在文档中记录了当时解决该问题的思路，参考文档，以及可选的其它方案，就能迅速的进入当时的状态，一切都很快清晰起来。

文档中写些什么。首先是概念强化，在需求中有哪些对象（名词），中英文分别是什么，对象间是什么关系。这样在代码中为对象或函数命名也会规范和一致。

其次是接口，包括软件所有暴露出来的行为。先是外部接口，比如，软件有哪些命令行参数？用户可以设置哪些环境变量来影响行为？它与其它系统如何交互？特别是与数据库的设计，记录的就是与数据库系统交互的接口。然后是内部接口，记录子模块间如何通讯，通讯协议，格式等。

再次，是专题问题。对某个独立的需求，设计其相关的数据模型，接口等。对某些疑难问题，记录下参考资料，核心难点怎样解决，可选办法以及如何决策等。

在写文档时有个重要原则：不要重复。在其它地方能够了解到的内容，就不必写到文档里，一是使文档更有价值，二是避免更新的麻烦。比如，如果软件能输出完整的命令行帮助信息，或是软件本身的帮助文档已经包括了这些内容，那么只要在设计文档里加上链接，让读者去更专业的地方来找就好了。一般过程是这样的，先是什么都写到设计文档中，然后再逐渐细分出其它文档。

创作之前，先想设计，写出提纲，再图实现。以此之道，终会受益。