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