我认为最好的文档是结构清晰、优雅易读的代码+简洁的注释,当然对于一个多人的团队项目、复杂的系统或高难的设计模式而言为了便于他人或自己日后能够更好的理解,是需要独立于代码的文档的。
但是文档只是为了达成知识传递目标的一种手段,如果这种手段是低效的,那就换一种手段。可是完全抛弃了文档是不可行的,难道每次沟通都完全用手比划,用嘴说,跟不同的人重复表述同样的想法?很显然,那样更低效。
应该清楚文档的本质是把知识显性化。在一个项目中存在很多需要沟通的知识,我们要认识到:不是所有的知识都是可以通过文档这种方式显性沟通的。知识具备两种形态,显性的和隐性的,只要我们做过程序员,并试图为自己的程序写文档时就会发现有很多隐藏在代码中的思想的闪光点是无法用文档这种方式100%的来传达的。
文档不是目的,有效沟通才是目的。而沟通是服务于整个项目的流程控制,所以结论是:文档的重要性 < 流程控制。
应该清楚文档的本质是把知识显性化。在一个项目中存在很多需要沟通的知识,我们要认识到:不是所有的知识都是可以通过文档这种方式显性沟通的。知识具备两种形态,显性的和隐性的,只要我们做过程序员,并试图为自己的程序写文档时就会发现有很多隐藏在代码中的思想的闪光点是无法用文档这种方式100%的来传达的。
文档不是目的,有效沟通才是目的。而沟通是服务于整个项目的流程控制,所以结论是:文档的重要性 < 流程控制。