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

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

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

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

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

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