在我的团队中，我们有一个很棒的源控制系统，我们有很好的规格。我想解决的问题是如何使规范与代码保持同步。随着时间的推移，规格趋于老化并变得过时
制作规范的人往往不喜欢源代码控制，程序员往往不喜欢sharepoint。
我很想听听其他人使用的解决方案吗？某个地方有幸福的中间人吗？
答案 0 :(得分：11)
不。中间没有幸福。他们有不同的受众和不同的目的。
以下是我作为建筑师和规范作者所学到的知识：规格几乎没有长期价值。克服它。
规范虽然很适合开始编程，但无论你做什么，它都会随着时间的推移而失去价值。规范的受众是一个没有太多洞察力的程序员。那些程序员变成了知识渊博的程序员，他们不再需要这些规范。
规范的某些部分 - 特别是概述 - 可能具有一些长期价值。
如果规范的其余部分有价值，那么程序员会让它们保持最新状态。
有效的方法是使用代码中嵌入的注释和工具来提取这些注释并生成当前的实时文档。 Java使用javadoc完成此操作。 Python使用epydoc或Sphinx执行此操作。 C（和C ++）使用Doxygen。有很多选择：http://en.wikipedia.org/wiki/Comparison_of_documentation_generators
概述应从原始规范中删除并放入代码中。
应提取最终文件。本文档可以使用规范概述和代码详细信息替换规范。
当需要进行大修时，会有新的规格。可能需要修改现有规范。起点是自动生成的规范文档。规范。作者可以从那些开始，添加/更改/删除他们内心的内容。
答案 1 :(得分：5)
我认为非Sharepoint wiki有助于保持文档的最新状态。大多数非技术人员都可以理解如何使用wiki，大多数程序员都非常乐意使用一个好的wiki。在我看来，Sharepoint中的wiki和文档控制系统使用起来很笨拙，令人沮丧。
Mediawiki是个不错的选择。
我真的很喜欢维基，因为它们是迄今为止采用和保持最低的痛苦。它们为您提供自动版本控制，通常非常直观，供所有人使用。很多公司都希望使用Word，Excel或其他类型的文档来实现这一目标，但是通过在线访问所有内容并从公共界面访问是关键。
答案 2 :(得分：4)
规范应该是可执行的，通过rspec，或doctest和类似的框架。应使用单元测试和具有良好命名方法和变量的代码来记录代码的规范。
然后规范文档（最好是在wiki中）应该为您提供更高级别的概述 - 并且不会发生太大变化或快速失去同步。
这种方法肯定会使规范和代码保持同步，并且当它们不同步时测试会失败。
话虽如此，在很多项目中，上面都是天上掉馅饼。在那种情况下，S。Lott是对的，克服它。他们没有保持同步。将规范视为开发人员给出的路线图，而不是他们所做的文档。
如果拥有当前规范非常重要，那么在编写代码之后，分配用于编写（或重写）规范的项目应该有特定的时间。然后它将是准确的（直到代码更改）。
所有这一切的替代方法是将规范和代码保持在源代码管理之下，并检查签入以确保规范随代码一起更改。它会减慢开发过程，但如果真的那么重要......
答案 3 :(得分：1)
对于你正在描述的内容，我不知道任何特别好的解决方案;一般来说，我见过的唯一真正保持这种东西同步的解决方案是从源代码生成文档的工具（doxygen，Javadoc）。
答案 4 :(得分：1)
用于使文档与代码保持同步的一种技术是literate programming。这使代码和文档保持在同一个文件中，并使用预处理器从文档中生成可编译的代码。据我所知，这是Donald Knuth使用的技巧之一 - 如果他们的代码中发现错误，他很高兴pay people钱。