使代码文档成为提交（或构建）的自动化要求。 [关闭]答案

【问题标题】：Making code documentation an automated requirement for a commit (or build). [closed]使代码文档成为提交（或构建）的自动化要求。 [关闭]
【发布时间】：2014-02-12 18:25:31
【问题描述】：

我即将开始一个大型 .js 项目，作为工作流程的一部分，我想强制执行代码文档。我倾向于 JSDoc (2.x)。

理想情况下，我想拦截未记录的代码。我对任何会感兴趣的东西都感兴趣：

使用 Grunt、Gulp 或类似工具在开发人员的机器上停止构建。
使用 git 挂钩来防止将未记录的代码推送到存储库。
运行服务器端部署前检查并导致构建失败。

【问题讨论】：

标签： git build gruntjs web-deployment jsdoc

【解决方案1】：

Git 可以在客户端上运行脚本以在提交或推送代码之前进行一些检查。

我不知道您可以在服务器上实际运行的任何脚本； Git 服务器不是很复杂，因为您可以随时撤消任何更改。

对我来说，将文档作为一项要求听起来也不是一种策略。通常需要文档来记录设计和代码中的错误和缺陷（即人们无法理解或使用产品没有 - 如果缺陷不存在，则无需解释如何使用它）。

根据我的经验，通过进行代码审查以确保质量保持较高，您会做得更好。

【讨论】：

+1 用于在将内容合并到主分支之前进行代码审查。我定期提交临时代码/我当前的状态，最后进行重构/清理令人困惑的部分和类似的东西。恕我直言，为每次提交甚至在运行测试之前强制执行此操作是一个坏主意。对于 git-commit-hooks，还有 --no-verify 忽略钩子，所以这并不总是有帮助。
我应该指定该要求应该在特定版本上强制执行。构建和部署到沙盒和开发环境很好。目标是针对任何更高的环境（Stage、QA、Prod）强制执行。
阅读本文时我的第一个想法是“所以文档是事后才想到的？”此外，您是否真的想为最简单的代码（如 Java 中的访问器方法）强制执行文档？如果有人告诉我在我的公司实施这个，我会辞职。如果有人要求我实现它，我会说训练一个 AI 需要 4-5 年，所以它不会要求无用的文档。您可能还想阅读以下内容：blog.pdark.de/2012/10/11/tnbt-documentation-sucks
还有一件事：强迫人们在代码中添加 cmets 不会给你提供好的文档。他们可以通过使用/* xxx */ 散布代码来通过测试。您希望他们给出一个概述（但代码中没有合适的地方来放置这个）或为什么有人想要使用某种方法。其他一切都是浪费时间。
该项目是一个 API，将被第 3 方使用。代码文档是一项业务需求。