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

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所述

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

希望它有所帮助。 我想许多公司可能会采取许多其他方式。