敏捷软件开发原则-可以工作的软件重于面面俱到的文档

2019独角兽企业重金招聘Python工程师标准>>>

    没有文档的软件是一种灾难。代码不是传达系统原理和结构的理想媒介。团队更需要编制易于阅读的文档，来对系统及其设计决策的依据进行描述。

　　然而，过多的文档 比过少的文档更糟。编制众多的文档需要花费大量的时间，并且要使这些文档和代码保持同步，就要花费更多的时间。如果文档和代码之间失去同步，那么文档就会变成庞大的、复杂的谎言，会造成重大的误导。

　　对于团队来说，编写并维护一份系统原理和结构方面的文档将总是一个好主意，但是那份文档应该是短小的 （short）并且主题突出的（salient）。“短小的”意思是说，最多有一二十页。“主题突出的”意思是说，应该仅论述系统的高层结构和概括的设计原理。

　　如果全部拥有的仅仅是一份简短的系统原理和结构方面的文档，那么如何来培训新的团队成员，使他们能够从事与系统相关的工作呢？我们会非常密切地和 们在一起工作。我们紧挨着他们坐下来帮助他们，把我们的知识传授给他们。我们通过近距离的培训和交互使他们成为团队的一部分。

　　在给新的团队成员传授知识方面，最好的两份文档是代码和团队。代码真实地表达了它所做的事情。虽然从代码中提取系统的原理和结构信息可能是困难的，但是代码是惟一没有二义性的信息源。在团队成员的头脑中，保存着时常变化的系统的脉络图（road map）。人和人之间的交互是把这份脉络图传授给他人的最快、最有效的方式。
　　许多团队因为注重文档而非软件，导致进度拖延。这常常是一个致命的缺陷。有一个叫做“Martin文档第一定律（Martin’s first law of documentation）”的简单规则可以预防该缺陷的发生：直到迫切需要并且意义重大时，才来编制文档。

 

------------------------------------------------------------------个人笔记

重视团队面授高于文档对于稳定的团队，以及持续投资，开发迭代的项目是有效的。毕竟程序员们的写作表达水平有限，时间有限。但是对于人员流动大，交接时间短的项目如果没有文档，又没人给你面授，那对于新人来说接收这个项目还是很难的，对于一些整体的架构设计，流程图，接口的入参，返回结果的详细说明还是有必要的。即便是代码的原作者时间长了也可能会忘记啊。所以 我觉得文档与代码注释是很有必要的，当然要跟上需求与代码的进度。

转载于:https://my.oschina.net/zhaolin/blog/2993377