表示编码标准最有用的方法是什么？

Question

我们目前将编码标准保存在SVN下的MSWord文档中。

随着我们的标准的发展/变化，它将成为一种越来越笨重的野兽。

目前大多数参赛作品包括：

• 对指南的简洁解释。
• 指南背后的推理。
• 任何额外的笔记。
• 你应该做什么的例子。
• 你不应该做的例子。

目前，我们在文档中使用跟踪更改来跟踪定期审核然后接受/拒绝的待处理建议/更正。

是否有一种事实上很好的方法来处理维护这样的文档？

Answer 1

GitHub的存储库服务很好。请参阅示例：https://github.com/airbnb/javascript - 您可以进行讨论，跟踪更改，接受/拒绝拉取请求等。

如果您使用插入构建过程的自动格式化工具（如https://golang.org/cmd/gofmt/或https://github.com/thoughtbot/hound

），也会有所帮助

Answer 2

我建议你在某个版本控制系统下使用纯文本文件（或HTML /其他一些标记文件，如果你需要一些花哨的格式）。我们使用Word的功能进行版本控制，我更喜欢Git提供的功能。

Answer 3

• GITHUB ：作为一个组织，如果您维护一个私有的Github存储库（不是开源，但利用Github的优势来维护存储库，允许分布式编码可供组织内的个人访问），您可以将您的编码标准文档上传到Github存储库，维护一个降价文档，该文档可能有评论/拉取请求等，如Alex above

• REVIEWBOARD ：如果您的组织没有私有Github存储库，那么如果您的组织通过以下方式执行代码审核，我建议您选择此选项审查委员会。 ReviewBoard允许通过同行审查代码，维护不同评论的数据，是否解决，是否允许发布版本等等。因此，您可以利用评审委员会的这一功能来审查编码标准文档。 ReviewBoard的功能为reviewing PDF documents。因此，我想通过此选项，您将维护CodingStandards文档的存储库，并提供审阅PDF文档的选项，该文档由ReviewBoard应用程序跟踪。

希望它有所帮助。我想许多公司可能还有很多其他方式可以做。