关于”代码既文档“的新思考

我原来也很赞成”代码既文档“的想法，认为有很大的可行性，只是没有发展出相应的流程和工具机制，才没有成功。

最近的一些思索让我发现这方面还没有那么简单，主要是在抽象级别方面。代码描述的是系统的内部实现构造，而文档描述的是系统的外在表现。

即使是加在代码上的结构化的注释，主要表达的也是系统是如何实现的，它可以说明一段代码，一个方法，一个类，甚至一个组件是做什么的，但这些依然不是系统最终用户所能直接理解和受益的资料。

对于软件工程来说，文档的作用是告诉不了解实现技术的人（如最终用户），系统是做什么的；或者告诉了解实现技术，但没有时间和必要性去深入细节的人（如实施人员），系统的实现思路。

系统的内在机制和外在表现之间需要知识介质联系起来，目前这种知识就体现在软件文档中。

评论

9 楼 congdepeng 2011-09-22  

代码既文档 还是 文档既代码。

DSL!

8 楼 huhang1986 2011-04-26  

文档是代码的冗余，所以同时维护代码和文档很痛苦。

7 楼 uda1341 2010-01-20  

1楼想法正点，现有的计算机语言抽象能力太弱，才导致文档必须与代码分离。

不仅如此，那样的理想语言会导致计算机软件体系的重大变革，从目前的各自为营的状态变成一个整体。

6 楼 xieshaohua 2009-11-14  

文档是代码的抽象。

5 楼 qqwjz 2009-06-03  

极限编程推荐的是：维护最小的文档集，不到迫不得不写文档的。对系统架构、系统分析等全局结构描述的文档是必不可少的。

4 楼 rubynroll 2009-05-14  

“代码即文档”，而不是 “代码即全部文档”，有些层次的文档是一定需要的。

3 楼 suifeng 2009-04-20  

集中在一起便于积累和维护，现在维护最大的问题就是文档不全，文档和代码不一致，修改之前，要理解原来作者的设计意图，如果所有相关文档都有，修改起来就很清晰．

2 楼 liujunsong 2009-04-20  

代码就是代码
文档就是文档
非要把两种东西搞一块,只能是搞的不伦不类,乱七八糟.
Java的doc就是典型例子,从里面找点东西出来,这个费劲啊

1 楼 suifeng 2009-04-20  

＂代码既文档＂的想法很好，很超前，极有可能是以后的发展方向．如果以后能出现一门抽象级别更高的语言，它能直接支持这想法，而现在的语言不支持这种想法（可能有，或许没发现），现在的语言大都依靠注释去完成用户接口．
　　如果有种语言能支持多视图：购买者视图，使用者视图，管理者视图，开发者视图，测试者视图，维护者视图，．．．；那么＂代码既文档＂，也许会可行．