思考详细设计——maillist中的讨论

        前几日，我将《思考详细设计》贴到了python-chinese maillist 里面，引起了进百封信的讨论。这是在我意料之中的，我的本意就是以我的帖子为引子，引出一些好的建议和探讨出来。而出乎我的意料的是，这次讨论也没有摆脱“开题——跑题——咬文嚼字的争论——开始人身攻击”的宿命。

      不过讨论与争论中还是有些观点值得大家分享的，所以在这里整理罗列出来。

 

       wang yingqi同学提倡代码文档化这种方式，他如是说：
        中小项目的开发文档应该与代码的关系更紧密些, 而大型项目的文档应该更关心框架而不是实现, 除了需求文档以外，设计文档不应该写的过于详细, 如果开发周期比较长, 那么十有八九文档都是过期的. 而需求文档是测试后期跟踪的标本, 是应该明确的，这可以避免发布前的程序/ 需求/ 测试三方扯皮的情况出现. 因此我个人比较提倡代码文档化, 注释详细, 甚至有工具直接将代码中的规范注释变为API 手册, 接口说明等. 没有几个程序员喜欢翻阅项目前人的文档. 甚至说将数据定义, 接口规范都放在单独的文档中, 维护成本太高. 也是不太自然的事情. 在我们还没成为印度软件工厂中的机器之前, 我们还是尽量的避开形式大于效果的框框!

 

这得到了guo dan同学的赞同：

我同意，我觉得单元测试用例和类似Javadoc 的接口文档基本上就足够了。跟踪一份详细设计文档的成本还是挺高的。

 

紧接不久limodou就提出了新的思路：

所谓设计文档，就是你的代码还没有编写出来为了交流，为了肯定你的方案而写的，因此肯定不能细到代码都出来了。只不过，我们一般进入了编程阶段就不再看文档和修改文档罢了。但其中肯定有不少的设计会发生变化。对于正在工作的人来说，因为他很熟悉，所以它认为可能并不重要，或不能看到更多的东西。但对于一个新手来说，首先看文档可能是先要做的，通过它可以了解项目的骨干，而不是陷入到代码海洋当中。好的文档很重要，但问题是，怎么写出好的文档，这是一个非常难的问题。

最近正在考虑" 文学编程" ，将文档和代码写到一起将是非常好的方式。它不同于在代码中写注释。因为注释还是属于代码的一个语法结构。而文学编程的思想是在文章中嵌入代码。这样你写的首先是一份文档。侧重点不同。

 

注释一般是对函数，类的说明。而文学编程不仅仅是这些，可以是任意的文档，可以描述算法，设计思想。总之你可以理解就是一篇文档。同时在文档中存在代码，而这些代码可以被工具抽取出来变成真正可行的程序。因此不象注释那样的简单。而且在文学编程中，代码块，文档块都是可以命名的，可以被相互引用。这一点一般的编程不会有命名的概念。如果你看到leo ，那么它是以一种树形结构来展示你的逻辑结构，而不是一个对象树之类的程序结构。

javadoc 是为了从代码中抽取文档，而文学编程我认为是从文档中抽取代码。

 

leo 是一个python 的工具。国内鲜有文学编程的东西，在啄木鸟社区的wiki 上可能有一些。国外你可以查一查：

http://www.literateprogramming.com/

 

limodou认为使用API doc作为详细设计只能在编码结束才能产出，这是我的回复：

使用类似于javadoc 这种东西来作为最后的设计文档，不一定要等代码都出来了。因为你可以采用TDD 的方式来进行设计。

 

Harry Moo同学为大家分享了自己的经验：

我觉得代码就是最好的设计文档，有完善的注释，清晰的函数名，一目了然的类名。然后给些简单文档描述一下大的架构和类层次就OK 了。

基本上，我现在都是用的重构开发，边写边调整，不过我做的项目都不是很大。

说一说我的文档编写历程吧。

1. 在第一家公司，比较重视文档，写代码前必须写好设计文档，那段时间的确锻炼了我的文档编写能力，也接触了很多的软件工程、软件文档方面的书籍和资料。但是写文档跟写程序一样，各人有各人的风格，往往相互间还要就文档风格进行争论，并且每个人都不太想看人家写的，甚至自己写过的都不想再看了。。。

2. 在第二家公司，是过了CMM3的，不过过完就完了，没人真的按CMM3走，那样走会死人的。。。但是我们使用了迭代开发，而且一直坚持了下来，有位兄弟说他们公司进行了一半就停了下来，可能是因为你们做的是项目，客户压力相对较大。迭代开发可能更加适合做产品的公司。在这家公司，我的文档明显就写的少了，只有一些大的架构和设计上的文档。

3. 如今的公司，我们很少写文档，即使写也坚决不用WORD、VISIO和RATIONAL这些大软件(太慢，用CVS管理也不方便)，我们只用TXT。业务流程、详细设计这些我们就随手在纸上画，只是为了帮助理清思路、理解需求和得到设计架构。最终，我们保留的就是大概两样东西：TXT描述的大体架构(包括类关系)和代码。

侯捷说的好：代码面前了无秘密。 ：）

 

到这里还算是在围绕着如何改进详细设计进行讨论，重点集中在文档编写上面，大概这真的是大家痛苦的地方。但不久，题目开始发散，讨论变成了对现状的控诉，有几位同学试图将话题从新引回正途，但是洪水一泻千里，拦都拦不住（看来大家对这更感兴趣）。

于是有人开始教导年轻人，“不要把技术看得太重，不要对什么“设计”、“框架”看得过于神圣，不要唯技术论。毕竟软件是个产业，不是基础科学，卖钱是最终目的，因此任何的技术都要为“卖钱”服务，无论在哪个国家哪个公司都是这样，除非你去FSF做自由软件。”

limodou同学，对此次讨论非常关注，也一直想维护这次讨论的本意，但是最终还是没有阻止宿命的发生。终于有人开始对几个看不顺眼的开骂了……

 

怎么来解决设计之痛，是逆来顺受还是寻找适合自己的方式，以便从苦海中解脱，都取决你自己。不妨做一个黑色幽默，来张有意思的图片吧——洋为中用之典范：