Rails 上でオープンソースの Web アプリケーションを開発しています。コードをできるだけ理解しやすく、変更しやすいものにしたいと考えています。私は単体テストで開発をテストしています。コードの多くは、テスト ケース (各コントローラー アクションが入力として期待するもの、出力用に設定されているインスタンス変数、ヘルパーの呼び出し方法、ビジネス ロジック) を通じて「文書化」されています。モデルに組み込まれているなど）。それに加えて、Rails の規則により、私のコードが規則に準拠している場合、多くのドキュメントが不要になります。
では、十分に文書化された Rails アプリケーションを持つことと、Don't Repeat Yourself に従おうとすることのバランスはどこにあるのでしょうか? Rails アプリで本当に役立つ (RDoc) ドキュメントと、単なる無駄とは何かについてのガイダンスが記載された、優れたブログや記事はありますか?
OK、これが正しいことかどうかはまったくわかりませんが、私がやろうと決めたのは次のとおりです。
まず、別の Rails 開発者なら、標準のモデル、ビュー、コントローラーのディレクトリに私が書いたすべてのコードの意図を、少なくともよく知っているだろうと思っていました。そこで、他のソース ファイルに RDoc を追加し始めました。lib/helpers と app/helpers に公正なコード コレクションを作成したことが判明したので、そこから始めました。私は各ヘルパー メソッドについてかなり一般的な関数レベルのドキュメントを作成し、意図に焦点を当て、メソッドと引数の命名が覚えやすいものを詳しく説明しました。コーナー ケース、引数の相互作用、またはエラー チェックのほとんどについては説明しませんでした。これらの詳細については、各メソッドの単体テストを参照してください。
これを行っている間に、ばかげたことを文書化するのではなく、メソッド シグネチャにかなりの変更を加えたことがわかりました。（クリーンコードを読みましたか？@unclebobmartin で？すべての面で優れていると思いますが、特にネーミングと自己文書化で優れています。) したがって、RDoc の追加作業に加えて、(必要な) リファクタリングにかなりの時間を費やすことになりました。まだ十分な距離が取れていなかったので、最初にコードを書いた後のリファクタリング パスで、これが思い浮かびました。おそらく、「RDoc の追加」に費やした時間の 80% は、「ヘルパー」ディレクトリ内のコードに費やされ、その大部分は、作成ではなくリファクタリングでした。したがって、誰も RDoc 自体を読んだことがなくても、これは貴重な演習だったと思います。
次に、コントローラーに目を向けました。scaffolding が各コントローラー メソッドで生成するものと一致するデフォルトの単一行コメントを RDoc の最初の行として残しました (例: "# GET /")。標準的な Rails のことだけを行うメソッドについては、他のドキュメントは追加しませんでした。文書化する価値のあるコントローラー メソッドで行った独自のことは、それらが返すもの (HTML 以外のデータ形式など)、目的 (標準 REST モデルを超えたアクションなど) に関係していることがわかりました。 Ajax リクエストを処理するためのもの)、およびそれらが非標準の URL 形式を使用しているかどうか。(これは実際には私のルート設定のドキュメントでしたが、config/routes.rb は RDoc の生成に使用されていないため....) アクションの動作についてはまったく説明していませんでした。私の自動テストは、誰かが知る必要のあるすべてのケース/動作を十分にカバーしていると感じています. 最後に、コントローラーが操作するモデル クラスに言及するクラス レベルのコメントを追加しました。これは、人々が推測できないためではなく、生成された HTML ページに便利なリンクが含まれるようにするためです。
最後に、モデルの作業を行いました。繰り返しになりますが、ここでは単体テストで十分であることを考慮して、動作 (ビジネス ロジック) を文書化しませんでした。私がしたことは、フィールド定義が db/schema.rb にあることを読者に思い出させることでした (ばかげているように感じましたが、Rails に慣れていない開発者が物事を理解しようとしている場合、すべての魔法のメソッドのベース名を思い出しても害はありません。 ）。また、モデルの振る舞いの多くは、Rails の宣言型ヘルパー メソッドがモデル クラス (validates_...、belongs_to など) によって直接呼び出されることによって実装されていることにも気付きました。この機能が何を達成するかを説明しようとするのではなく (結局のところ、望ましいモデルの動作はテストによって「説明」されます)、モデルのソースを確認することを忘れないでください。(残念なことにRDocはそうではありません'
そして、それはそれでした。おそらく私が書く必要があるよりも少し RDoc が多いですが、コードが進化しても維持されるほど十分に軽量であり、単体テストによって「表現された」ものとはまったく重複しないと思います。うまくいけば、Rails 開発者が規則から推測できることと、ソースからしか理解できないこととの間のギャップが埋められます。(ただし、ビューからより多くの部分をヘルパーにプルしたいという衝動が高まっていることに気付きましたが、それらは再利用されておらず、ERB のインライン HTML を失うことを意味します。それらの説明を記述できるようにするためです。図を参照してください。)
コードを読んでも明確でないものはすべて文書化します。自己文書化コードは Ruby で簡単に実現できますが、狡猾なロジックにはコメントが必要です。rdoc が必要かどうかを判断するときは、プロジェクト初心者の立場になってみてください。それが必要かどうかを考えているなら、それが必要である可能性があります。最後に、アプリケーション コードのドキュメントを提供するためにテスト ソースに依存するつもりはありません。プロジェクトに飛び込んで、モデルが特定の方法で動作する理由について頭を悩ませていた場合、答えを得るためにすぐに単体テストを実行しないことを私は知っています。
私の短い答え: モデルはアプリケーションに本当に固有のものであるため、モデルを rdoc します。
しかし、Web アプリケーションを構築しているように聞こえるので、他の部分も rdoc する必要があるという議論がなされる可能性があります。