关闭。这个问题不符合 Stack Overflow guidelines 。它目前不接受答案。
想改善这个问题吗？更新问题，以便堆栈溢出为 on-topic。
3年前关闭。
Improve this question
在我的团队中，我们拥有出色的源代码控制系统和出色的规范。我想解决的问题是如何使规范与代码保持同步。随着时间的推移，规范往往会老化并过时
制定规范的人往往不喜欢源代码控制，而程序员往往不喜欢 sharepoint。
我很想听听其他人使用什么解决方案？某处有快乐的中间吗？
最佳答案
不。没有快乐的中间。他们有不同的受众和不同的目的。
以下是我作为架构师和规范编写者所学到的: 规范几乎没有长期值(value)。 克服它。
这些规范虽然很适合开始编程，但无论您做什么，都会随着时间的流逝而失去其值(value)。规范的受众是没有太多洞察力的程序员。这些程序员变成了不再需要规范的知识渊博的程序员。
规范的一部分——特别是概述——可能有一些长期值(value)。
如果规范的其余部分有值(value)，程序员就会使它们保持最新状态。
有效的是使用嵌入在代码中的注释和一种工具来提取这些注释并生成当前的实时文档。 Java 使用 javadoc 做到这一点。 Python 使用 epydoc 或 Sphinx 执行此操作。 C(和 C++)使用 Doxygen 。有很多选择:http://en.wikipedia.org/wiki/Comparison_of_documentation_generators
概述应该从原始规范中取出并放入代码中。
应提取最终文件。本文档可以通过使用规范概述和代码详细信息来替换规范。
当需要大修时，会有新的规范。可能需要修改现有规范。起点是自动生成的规范文档。规范。作者可以从这些开始并添加/更改/删除他们的核心内容。
关于version-control - 如何保持代码和规范同步？ - 有没有好的工具，我们在Stack Overflow上找到一个类似的问题：https://stackoverflow.com/questions/913303/