我正在 Rails 之上开发一个开源 Web 应用程序。我想让我的代码尽可能容易理解和修改。我正在用单元测试来测试我的开发，所以很多代码都是通过测试用例“记录”的（每个控制器操作期望作为输入，为输出设置了哪些实例变量，应该如何调用帮助程序，什么业务逻辑模型合并等）。最重要的是，在我的代码符合它们的地方，Rails 的约定应该使大量文档变得不必要。
那么，拥有一个有据可查的 Rails 应用程序和努力遵守 Don't Repeat Yourself 之间的平衡点在哪里？是否有任何好的博客或文章指导哪些（RDoc）文档在 Rails 应用程序中真正有用，哪些只是浪费？
好的，完全不确定这是正确的，但这是我决定做的：
首先，我认为其他 Rails 开发人员至少会熟悉我在标准模型、视图、控制器目录中编写的所有代码的意图。因此，我开始在其他源文件中添加 RDoc。事实证明，我已经在 lib/helpers 和 app/helpers 中建立了相当多的代码集合，所以从那里开始。我为每个辅助方法编写了相当典型的函数级文档，重点关注意图，并确保我已经说明了方法和参数命名是助记符的内容。我没有描述大多数极端情况、参数交互或错误检查，将这些细节留给阅读每个方法的单元测试。
我发现在执行此操作时，我对方法签名进行了很多更改，而不必记录做了一些愚蠢的事情。（你读过干净的代码吗？通过@unclebobmartin？我认为它在所有方面都很棒，尤其是在命名和自我文档方面。）因此，除了作为 RDoc 添加练习之外，我最终花费了大量时间进行（需要的）重构——那些没有'在我第一次编写代码之后的重构过程中我没有想到，因为我还没有足够的距离。也许我花在“添加 RDoc”上的 80% 时间都花在了我的“helpers”目录中的代码上，其中大部分时间是重构而不是编写。所以，即使没有人读过 RDoc 本身，我认为这是一个很有价值的练习，我很高兴我花时间
接下来，我转向我的控制器。我留下了与脚手架在每个控制器方法上生成的内容相匹配的默认单行注释作为 RDoc 的第一行（例如，“# GET /”）。对于只做标准 Rails 的方法，我没有添加任何其他文档。我发现我在控制器方法中所做的值得记录的独特事情与它们返回的内容（例如，HTML 以外的数据格式）、它们的用途（超出标准 REST 模型的操作，例如那些旨在为 Ajax 请求提供服务），以及它们是否使用非标准 URL 格式。（这确实是我的路由配置的文档，但是由于 config/routes.rb 不用于生成 RDoc....）我根本没有描述我的操作的行为，感觉我的自动化测试足以涵盖某人需要知道的所有案例/行为。最后，我添加了提到控制器操作的模型类的类级注释，不是因为人们无法猜测，而是为了在生成的 HTML 页面中有一个方便的链接。
最后，我在我的模型上工作。同样，我没有记录行为（业务逻辑），考虑到我的单元测试在这里就足够了。我所做的是提醒读者字段定义在 db/schema.rb 中（感觉很傻，但是如果一个刚接触 Rails 的开发人员试图弄清楚，提醒所有魔术方法的基本名称不会有什么坏处）。我还意识到，我的许多模型行为都是通过模型类（validates_...、belongs_to 等）直接调用的 Rails 的声明性辅助方法实现的。我没有试图描述这些东西完成了什么（毕竟，所需的模型行为是由测试“描述”的），我只是提醒你查看模型源。（很遗憾 RDoc 不是
就是这样。可能比我需要编写的 RDoc 多一点，但我认为它足够轻，可以随着代码的发展而得到维护，并且它根本不会与我的单元测试“表达”的东西重叠。希望它填补了 Rails 开发人员可以从约定中推断出的内容与您只能从源代码中得出的内容之间的空白。（尽管我现在注意到越来越多的冲动将我的视图中的更多部分提取到帮助程序中，即使它们没有被重用，这意味着丢失 ERB 的内联 HTML，只是为了我可以为它们编写描述。去图。）
我的简短回答： rdoc 你的模型，因为它们对你的应用程序来说是独一无二的。
但是听起来您正在构建一个 Web 应用程序，因此可以提出您也应该 rdoc 其他部分的论点。
记录任何通过阅读代码并不清楚的内容。使用 Ruby 可以轻松实现自记录代码，但狡猾的逻辑需要注释！在决定是否需要 rdoc 时，试着让自己站在项目新手的立场上。奇怪的是，如果您正在考虑它是否需要它，它确实需要。最后，我不会依赖测试源来为您的应用程序代码提供文档。我知道，如果我跳入一个项目并且对模型为什么以某种方式表现而摸不着头脑，我不会立即跑到单元测试中寻找答案。