由work撰写的日志

我觉得这篇写不长，因为其实关于文档的一些理念基本都是那种说着很简单，做着很难的。

文档多了好？

记得以前看CMM的时候，很强调文档的重要性。这是为什么咧？因为CMM是典型的软件工程理论嘛，而软件工程怎么来的咧？就是从建筑工程学来滴嘛。君不见，黄河之水天上来盖栋房子得有多少文档啊，来描述这个建筑的架构，每个房间的布局。这啊哪的，反正肯定很多就是了。都是设计师仔仔细细设计规划好弄好了，然后由俺们最可耐滴农民工一砖一瓦的，蹭蹭的，一栋building就出来了。所以CMM挺强调文档滴，整个软件周期，都要有这文档那文档的，堆积如山的。而实际效果呢？用猜的也知道肯定不怎么好了，不然现在人都表当自个Agile，而不说自个CMM了呢。

好吧，那你说这是为什么呢？我来告诉你。如果你建个大楼，建完之后你会没事拆着玩么？比如把18~20楼拆了，换个盖法。或者把楼里的钢筋全换一遍，换个回扣给的工作的牌子。你不会吧。所以你盖好之后，你那份文档描述的就是你的building，所以可以从下水道偷偷溜到你楼顶。所以这份文档是即使的反映了这个building的结构与状态的。

反过来，看软件开发。你能保证你写完之后的code有几天不被改？重写，重构，bug fix，需求变更。这些常见的活哪个不是要你改code。而你弄了那么多的文档，最后发现和code完全不一致了，那你说这效果能好么。文档说CLASS A是干这事的。结果一看code发现CLASS A根本就不是干那事的。当然，也可能你根本已经找不到CLASS A这么一个玩意儿了。

所以说文档足够多并不一定好，因为软件开发中，变化是从头到尾的。所以如果文档的变化跟不上项目的变化，太多的过时信息。最终非但不能帮助项目，却还会拖后腿，造成更多的怀疑，浪费经历。

少就是多？

爱扯Agile的肯定都说过这么一句话：代码即文档。

嗯，如果我没记错，好像这句应该是敏捷宣言中的？（刚查了下，原话和我记性不太一样，原话是：Working software over comprehensive documentation.）就是说如果你的代码写的足够好，本身就足够说明很多问题（比如通过起带有意义名字的变量，比如使用元数据编程，比如加恰当的注释）。那么就不需要和外在另外一个地方写场面大论来描述代码是怎么回事。

其实这方面我觉得很有代表性的就是javadoc和Xdoclet。javadoc也影响了很多后来的框架和语言啊。因为做的确实不错。通过在注视中加入一些符号，可以自动通过程序来抽象出注释，组成有意义的文档。这是多么automatic的事情。而且特别是你的注释和你的code在一起，就减少了很多两遍对不上，描述过时这类的事情。Xdoclet当然也是关于这方面的一个工具吧。

嗯，还有元数据以及DSL这种编程方式也在很大程度上为代码可读性做出了优秀的贡献。

比如Rails中，在Model之间声明关系用的belongs_to, has_many之类的关键字（当然，其实他们不算关键字，也是方法，只是表现形式cool了些）。是多么的简洁，有力，聪明，异动啊。

所以我基本上很赞成，因为大科学家爱因斯坦都说简洁性就是一种美。因为俺觉得懒惰的程序员才是好程序员。如果代码就够清楚的，或者通过代码就能生成出来很清楚的文档，那么鬼才写文档。当然，其实这观点是偏激的。因为我们确实需要文档。因为代码只能从微观角度看问题，即便你给我一个SDK文档，我还是很难看出你当初都是为什么这么设计，那么构造之类的。So，我们依然需要文档。但是要强调一定，我们需要的是高质量的文档，正确的文档。因为Diane说过：方向很重要（嗯，某次开大会说滴，很富哲理啊）。文档都是错了，就算你看个三天三夜，你也只能越看越错下去。所以，文档只有在正确的时候，才具有很大的重要性。如果只是过时的玩意儿，那么不如放到回收站吧。

The End

到现在，观念应该清楚了，文档其实还是需要的，但是我们如何去写文档呢？怎么使得文档是正确，有重大价值的呢？

嗯，我又发明了一个小所写KISSS原则。全称是：Keep it simple, stupid and synchoronous with your project. 嗯，别小看后半句噢，其实是一件非常难滴事情呢。因为锻炼你的写作技巧，尽量使得文档简洁又易懂，也许需要一些时间的锻炼，都能达到。但是synchoronous with your project需要的可是你长期的坚持啊。如果你的项目中某方面的改变牵扯到一些文档，会造成一些文档的过时，那么不要犹豫，立即更新它吧。真的不骗你，bad document的味道不比代码中bad smile造成的伤害小多少。

好吧，最后的结论就是，尽量写具备自描述能力的代码。如果某些时候，必须要写文档才能解决问题的时候，记得随时更新它。使它和你的项目保持同步。