软件文档写完就过时了吗？

最近在写FPM的需求规格说明和软件设计说明的文档，有一些感触。

写文档是有好处的。比如需求规格说明，就是在你接受了任务之后，对任务的理解，对将要设计的软件的功能的梳理。也就是说，你拿到一个软件开发任务后，应仔细思考，软件应以什么样的形式呈现，软件的使用方式，软件的状态转移过程，软件的数据流图是什么样的。软件应有什么样的功能，才能满足任务书的要求。为了说明各个功能，需要对其稍加描述，并辅以输入输出接口。所以，需求规格说明的输入是任务书。

而软件设计说明的输入则是需求规格说明。需求规格说明规定了软件是什么样子，应有什么功能。软件设计说明则详细地说明这些功能将如何实现。从宏观上看，要决定软件设计的策略，软件的架构。从微观上看，要决定各个功能的如何实现，使用什么数据结构，使用什么算法。特别是使用什么算法，需要详细说明。这样才能知道这个算法是否可行。

软件文档

但是，文档究竟写到什么程度，确实很难界定的。

比如，软件需求规格说明里的功能分解，你可以分解地很详细，细粒度，也可以简略点，粗粒度。同样，对于软件设计说明，对每一个功能，可以描述地很详细，也可以很简略。特别是对用到的数据结构，它应有什么样的字段，可以确定一些，但很难全部确定。

正如George Fairbanks在《恰如其分的软件架构》中所述，“若你看到开发者编写了太多的文档，又或者未经深思熟虑就急于编写代码，一定会认识到这种软件开发方式的谬误。”

一般而言，如果软件难度较小，倾向于写得简略点，如果难度较大，对于其中的难点，倾向于写得详细一点。

所以，文档一旦写完归档，没有谁愿意再去修改它。从这一刻起，注定了文档与软件的脱离。一方面，通过写一些文档，梳理了思路，对将要设计的软件有了新的认识，但这些新的认识不会再反馈到文档中去。另一方面，在软件编写中，会根据实际情况进行调整，确定全部的细节，但这些也不会再反馈到文档中。

这一点和硬件设计不同。硬件设计根据图纸制成电路板。在制成电路板之前，图纸必须确定，不可有未决之处。而软件不同，软件不能通过软件设计说明自动生成，即使软件设计说明写得再详细，写代码时一点也不会少。

因此， 软件文档本身对软件没有约束力。

很多工具致力于由文档生成代码，但差强人意。反过来，程序员更喜欢由代码生成文档，有很多这方面的工具，比如gtk-doc，javadoc等。

但如果先有软件，后有文档，那么这些文档对设计就没有意义了，但是，对软件维护还是很有意义的。