代码整理工具_文档代码同源

文档代码同源，故名思意，就是文档和代码都写在源代码文件里。这样可以：1.修改代码的时候就及时修改文档，使得文档和代码及时保持一致；2.阅读代码时，增加代码的可读性。评审代码的时候，尤其是修改时后，即对文档一同评审。结合研发流程、评审的配合，可促使代码、文档的开发逐步走向一一对应，逐步向高质量发展，同时也能提高团队素质。

一、问题起源

互联网行业和一些物联网行业，软件开发都提倡敏捷开发，敏捷开发为何物？(附件介绍。)这里列出敏捷的宣言：

个体和互动 高于 流程和工具

工作的软件 高于 详尽的文档

客户合作 高于 合同谈判

响应变化 高于 遵循计划

也就是说，尽管右项有其价值，

我们更重视左项的价值

很多公司所谓的敏捷，很大程度上就是开发代码，应该有的必要文档可能都是不全的。因为要赶工，因为市场的巨大压力，文档代码对应不上司空见惯。更有甚者，压根就没有文档。这里造成了很多隐性的问题。

1.没有合适的文档，随着时间的推移，一些技术要点，设计要求，设计思路随着时间，尽归尘土。这些通过市场、技术、商业等各个维度试错的来的宝贵经验和知识无法传承，是一种浪费，更是一种低效组织的表现。

2.关键岗位的开发人员一旦流失，产生的技术、知识断崖，短期内难以补足。

3.新人的进入，需要长时间的消化理解。

4.代码的评审和检查不严格，想怎样改就怎样改，只要外在的功能是正常的。那就是没有问题的。为很多问题埋下了伏笔和隐患。

敏捷中有一个观点，窃以为是无比正确的：没有什么文档比代码更准确。但这个观点又是比较危险的:

1.可运行的功能正确的代码的确是没有什么比其更准确的了。但是，代码毕竟是写给机器运行的，个人的能力、习惯等都不一致，其他人理解起来必然费劲。有一些饱含技巧的写法可能是需求的需要，也可能是个人炫技的需要；其他人又怎能看透全部呢？代码毕竟是非自然语言，有时候能看得懂代码，是以牺牲速度为代价的，总之，问题