stu*_*uck 13 documentation version-control specifications
在我的团队中,我们有一个很棒的源控制系统,我们有很好的规格.我想解决的问题是如何使规范与代码保持同步.随着时间的推移,规格趋于老化并变得过时
制作规范的人往往不喜欢源代码控制,程序员往往不喜欢sharepoint.
我很想听听其他人使用的解决方案吗？某个地方有幸福的中间人吗？
S.L*_*ott 11
不.中间没有幸福.他们有不同的受众和不同的目的.
这就是我作为建筑师和规范作者所学到的: 规格几乎没有长期价值. 克服它.
无论你做什么,规范虽然很好地开始编程,但随着时间的推移会失去价值.规范的受众是一个没有太多洞察力的程序员.那些程序员变成了知识渊博的程序员,他们不再需要这些规范.
规范的一部分 - 特别是概述 - 可能具有一些长期价值.
如果规范的其余部分具有价值,程序员将使它们保持最新.
有效的方法是使用代码中嵌入的注释和工具来提取这些注释并生成当前的实时文档.Java使用javadoc完成此操作.Python使用epydoc或Sphinx执行此操作.C(和C++)使用Doxygen.有很多选择:http://en.wikipedia.org/wiki/Comparison_of_documentation_generators
概述应该从原始规范中取出并放入代码中.
应提取最终文件.本文档可以使用规范概述和代码详细信息替换规范.
当需要进行大修时,会有新的规格.可能需要修改现有规范.起点是自动生成的规范文档.规范.作者可以从那些开始,添加/更改/删除他们内心的内容.