文档代码同源_怎样让文本文档和代码同步-CSDN博客

文档代码同源，故名思意，就是文档和代码都写在源代码文件里。这样可以：

1、修改代码的时候就及时修改文档，使得文档和代码及时保持一致；

2、阅读代码时，增加代码的可读性。评审代码的时候，尤其是修改时后，即对文档一同评审。结合研发流程、评审的配合，可促使代码、文档的开发逐步走向一一对应，逐步向高质量发展，同时也能提高团队素质。

1、问题起源

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

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

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

客户合作高于合同谈判

响应变化高于遵循计划

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

我们更重视左项的价值

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

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

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

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

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

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

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

2.潜台词是，文档不重要。

总之，文档、代码的问题，不仅困扰着程序员，也困扰着公司。那么怎么找一个合适的方法解决这个问题呢？

2、解决方案

想想程序员为什么写或修改代码？我想即使是为了拯救地球和全宇宙，从微观上讲，也符合下列情况之一：

1.实现需求。是的，这怕是程序员写/修改代码的第一大原因了。

2.抓Bug。程序员实现需求的副产品：八阿哥(bug)。把它送走，是我们改代码的第二大驱动。

3.其他原因，诸如设计不足，可理解性不好啦，模块用起来不爽啦，封装不够简洁实用，有一些程序员还有洁癖。这可能都是修改代码的原因。但从本质上来讲，也是满足需求的修改。每个产品需求定义之外，都有灰色边界。需求提得越清楚，灰色地带就越少。阅读性不好、模块用起来不爽，可能在需求里没有提出来。有些作为需求提出来，也是可以的。比如说，对于产品某个模块的要求，必须使用什么标准技术或模块，或者必须满足下一代的复用等。至于洁癖，团队没有定义团队的写法，那么冲突修改是必然的。

代码中所有的修改都可归为这三类，更进一步，大部分应该是前两类。开源世界有一个很好用的工具是Doxygen。它的作用就是把代码里的特殊注释抽取出来变为文档(一个类似Latex的工具，非所见即所得的文档编辑工具)。我们的思路就是，利用Doxygen工具，将代码和文档的开发变为同步过程。由于文档含在代码里，也意味着Doxygen的文档也是文本，在版本库的管理下，能精确的看到每一个比特的修改。(后面有文章做一个的Doxygen介绍。)这里简单的介绍一下Doxygen。

Doxygen 是一个程序的文档产生工具，可将程序中的特定注释转换成为说明文件。比如说对于以下这段注释：