好的,完全不确定这是正确的,但这是我决定做的:
首先,我认为其他 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,只是为了我可以为它们编写描述。去图。)