我正在開發一個基於Rails的開源Web應用程序。我想讓我的代碼儘可能容易理解和修改。我正在使用單元測試來測試我的開發，所以很多代碼都是通過測試用例「記錄」的（每個控制器操作期望輸入的內容，爲輸出設置了哪些實例變量，應該如何調用助手，什麼業務邏輯模型合併等）。最重要的是，在我的代碼符合它們的情況下，Rails的約定應該使大量文檔變得不必要。Ruby-on-Rails應用程序的哪些部分（具有合理的表達性單元測試）應該有RDoc？
那麼，在哪裏有一個證據充分的Rails應用程序，並試圖服從不要重複自己之間的平衡？有什麼好的博客或文章可以指導哪些（RDoc）文檔在Rails應用程序中真正有用，什麼是浪費？
我的答案很簡單：你的RDoc車型，因爲他們是真正獨一無二的應用程序。
但聽起來好像你正在建設一個Web應用程序，這樣的說法可以作出，你應該RDOC其他部分了。
OK，不能肯定這是正確的事情，但這裏是我決定做：
首先，我認爲其他的Rails開發者熟悉所有的至少意圖我在標準模型，視圖，控制器目錄中編寫的代碼。所以，我開始在其他源文件中添加RDoc。事實證明，我已經在lib/helpers和app/helpers中建立了一個公平的代碼集合，所以從那裏開始。我爲每個幫助器方法編寫了相當典型的函數級文檔，重點關注意圖，並確保我詳細說明了方法和參數命名的助記符。我沒有描述大多數角落案例，參數交互或錯誤檢查，只是將這些細節留給每個方法的單元測試讀取。
我發現我是這樣做的同時，有相當我到方法簽名製成，而不是記錄已經做了一些愚蠢的幾個變化。 （你是否讀過@unclebobmartin的Clean Code？我認爲它在所有方面都很出色，特別是在命名和自我記錄方面。）因此，除了作爲RDoc增加練習之外，我最終花費了大量的時間（需要的）重構 - 在我第一次編寫代碼之後重構過程中沒有發生的事情，因爲我還沒有足夠的距離。也許80％的時間我「加入RDoc」花在我的「助手」目錄中的代碼中，其中大部分是重構而不是寫作。所以，即使沒有人讀RDoc的本身，我認爲這是一個寶貴的鍛鍊和我很高興我花的時間
接下來，我轉向控制器。我將默認的單行註釋與每個控制器方法在腳本生成的腳本作爲RDoc的第一行（例如「＃GET /」）進行匹配。對於只執行標準Rails的方法，我沒有添加任何其他文檔。我發現我在我的控制器方法中做的值得記錄的獨特的事情必須與他們返回的內容（例如HTML以外的數據格式），它們的用途（超出標準REST模型的操作，比如那些旨在服務於Ajax請求）以及它們是否使用非標準的URL格式。 （這實際上是我的路由配置的文檔，但是因爲config/routes.rb沒有用於生成RDoc ....）我沒有描述我的行爲，因爲我的自動化測試充分覆蓋了所有有些人需要知道的案例/行爲。最後，我添加了提及控制器操作的模型類的類級註釋，不是因爲人們無法猜測，而是爲了在生成的HTML頁面中有一個方便的鏈接。
末，我曾在我的模型。再次，我沒有記錄行爲（業務邏輯），考慮到我的單元測試在這裏足夠了。我所做的就是提醒讀者，字段定義在db/schema.rb中（感覺很愚蠢，但是如果一個剛接觸Rails的開發人員試圖弄清楚事情的真相，提醒所有魔法方法的基名不會受到傷害）。我也意識到，我的很多模型的行爲是通過模型類直接調用Rails的聲明輔助方法實現的（驗證_...，belongs_to等）。與其試圖描述這些東西完成什麼（畢竟，期望的模型行爲是由測試「描述」的），我只是提醒我們看一下模型的來源。 （這是一種恥辱，RDoc沒有意識到Rails約定能夠提取和記錄這些事情，就像Ruby常量定義一樣。）
就是這樣。也許我需要寫一些RDoc，但我認爲它足夠輕便，隨着代碼的發展它會得到維護，並且它與我的單元測試「表達」的東西完全不重疊。希望它填補了Rails開發人員從常規中可以推斷的內容和你只能從源代碼中找出的東西之間的差距。 （儘管我現在注意到越來越多的衝動將更多作品從我的觀點引入幫助者，儘管他們沒有被重用，並且這意味着要失去ERB的內聯HTML，以便我可以爲他們編寫描述。
記錄讀取代碼時不清晰的任何內容。使用Ruby可以輕鬆實現自行編寫代碼，但狡猾的邏輯需要註釋！在決定是否需要rdoc時，儘量讓自己置身於項目新手的角度。可能性是，如果你想知道它是否需要它，它確實如此。最後，我不會依賴測試資源爲您的應用程序代碼提供文檔。我知道，如果我跳上了一個項目，並且爲了模型的某種特定行爲而徘徊不前，我不會馬上跑到單元測試中尋求答案。