如何保持代码和规范的同步？--有没有好的工具

Question

在我的团队中，我们有一个很好的源码控制系统，我们有很好的规范。我想要解决的问题是如何使规范与代码保持最新。随着时间的推移，规格往往会老化并过时。

制定规范的人倾向于不喜欢源代码控制，程序员倾向于不喜欢sharepoint。

我很想听听其他人使用什么解决方案？在某个地方有快乐的中间吗？

Answer 1

不是的。没有快乐的中间。他们有不同的受众和不同的目的。

这是我作为一名架构师和规范撰稿人学到的：规范几乎没有长期价值。克服它吧。

规范，虽然很适合开始编程，但随着时间的推移，无论您做什么，都会失去它们的价值。该规范的受众是没有太多洞察力的程序员。这些程序员变成了知识渊博的程序员，他们不再需要这些规范。

规范的某些部分--特别是概述--可能具有一些长期价值。

如果规范的其余部分有价值，程序员就会让它们保持最新。

有效的方法是使用嵌入在代码中的注释和一个工具来提取这些注释并生成当前的实时文档。Java通过javadoc实现了这一点。Python使用epydoc或Sphinx实现这一点。C(和C++)使用Doxygen。有很多选择：http://en.wikipedia.org/wiki/Comparison_of_documentation_generators

概述应该从原始规范中删除，并放入代码中。

最终文档应该被提取出来。本文档可以通过使用规范概述和代码详细信息来替换规范。

当需要大修时，将会有新的规范。可能需要对现有规范进行修订。起点是自动生成的规范文档。规格。作者可以从这些内容开始，然后添加/更改/删除他们的核心内容。

Answer 2

我认为非Sharepoint wiki对于保持文档更新是很好的。大多数非技术人员都能理解如何使用wiki，并且大多数程序员都非常乐意使用一个好的wiki。在我看来，Sharepoint中的wiki和文档控制系统使用起来既笨重又令人沮丧。

Mediawiki是一个很好的选择。

我真的很喜欢wiki，因为到目前为止，他们是采用和保持最低痛苦的。它们为你提供了自动的版本控制，并且通常每个人都可以非常直观地使用。许多公司都希望使用Word、Excel或其他类型的文档来实现这一点，但关键是将所有内容都放在网上，并从一个公共界面进行访问。

Answer 3

规范应该尽可能是可执行的，通过rspec，或者doctest和类似的框架。代码的规范应该通过单元测试和具有良好命名的方法和变量的代码来记录。

然后，规范文档(最好是在wiki中)应该为您提供更高层次的概述-这不会有太多变化，也不会很快失去同步。

这样的方法肯定会使规范和代码保持同步，当它们不同步时，测试将失败。

话虽如此，在许多项目中，上述都是一种空中楼阁。在这种情况下，S. Lott是对的，克服它。它们不会保持同步。把规范看作是给开发人员的路线图，而不是他们做了什么的文档。

如果有一个最新的规范非常重要，那么在代码编写完成后，应该在项目中分配特定的时间来编写(或重写)规范。那么它将是准确的(直到代码发生变化)。

所有这一切的替代方案是将规范和代码置于源代码控制之下，并审查签入，以确保规范随代码一起更改。它会减慢开发过程，但如果它真的那么重要...