強制方法的文檔

在我以前的工作，提供與javadoc的所有方法是強制性的，這導致了諸如：強制方法的文檔

/** 
* Sets the Frobber. 
* 
* @param frobber The frobber 
*/ 
public setFrobber(Frobber frobber) { ... }

正如你可以看到，文件佔用空間和工作，但增加了小到碼。

應記錄所有方法是強制性的還是可選的？有哪些方法可以記錄的規則？什麼是需要記錄每種方法的優點和缺點？

來源

2010-03-16 Sjoerd

「提供與javadoc的所有方法是強制性的」

我強烈懷疑，記錄所有的方法是強制性的，但提供的javadoc註釋是所有可以自動執行，因此所有均勻地完成。

我個人認爲最好是沒有的Javadoc不是完全沒用的javadoc - 至少可以從哪些方法都是無證的HTML一看便知，因爲沒有參數等

文檔是描述經常被低估，因爲在編寫代碼時，它總是看起來不那麼重要和緊迫，而不像以後使用它的時候那樣。但文檔的風格和形式經常被高估 - 自動生成的XML廢話仍然是無稽之談。鑑於選擇，我寧願讓代碼評論// Sets this object to use the specified frobber for all future frobbing，比你的零信息javadoc。

對於所有我從你的文檔知道，該功能實際上並沒有修改this對象的話，那可能會呼籲frobber的set()功能，也可能是while(!frobber.isset()) { refrigerator.add(frobber); sleep(3600); refrigerator.remove(frobber); }故曰「設置frobber」。我確定我在某處讀到「set」是OED中定義最明確的詞。簡要說明不明確，因此具有誤導性，文檔的目的是阻止依賴您的信息來源的人員，從而阻止您當前實施的細節。我的評論並沒有真正花費時間去編寫，而是將「設置frobber」和「frobber」添加到IDE生成的javadoc存根中。它並沒有解釋什麼是抖動或者什麼時候這個對象會這樣做（希望這是類文檔中的其他地方），但至少它試圖告訴你函數的功能。

至於何時要求文件 - 我認爲每個接口必須記錄。如果您沒有定義Java interface，則「接口」是每個公共和受保護的方法，以及每個受封裝保護的方法，除非該封裝很小。實施不必記錄在案，但應該評論它的工作方式是否不明顯。文檔可能與我上面評論中的句子一樣簡單 - 如果方法描述已經說明它們是什麼，那麼對於每個參數，您不一定需要單獨的句子。

如果您有代碼審查，那麼IMO的答案是同時審查意見和文檔。如果你沒有代碼審查，那麼你需要一個cone of shame，無論哪個開發人員最近都迫使別人過來問問代碼實際上做了什麼。

同樣的情況也適用於任何依賴函數未記錄行爲的人，結果是沒有改變接口的實現更改，破壞他們的代碼。你將這些代碼的執行方式記錄下來，就是抱怨說，除非你知道它保證做什麼，否則你不能調用它。像「javadoc註釋必須存在」這樣的任意規則變得不那麼重要，至少對於其他開發人員需要調用的函數來說。

來源

2010-03-16 14:45:58

對於大項目或框架/庫，甚至你正在創建的開源項目，這是強制性的。對於小型個人或私人項目，它是可選的。話雖如此，將代碼記錄下來總是一個好主意，所以如果你在一年之後回到你的項目中，無論規模大小，你都知道它在做什麼。這真的很有幫助。

來源

2010-03-16 08:13:42 Sarfraz

文檔很重要，但您必須確保它與代碼同步。特別是對於給定的例子，Javadoc是多餘的，並沒有任何幫助。這可以通過強制Javadocs來輕鬆生成。我認爲推薦Javadoc的關鍵部分更有用。 – Mnementh 2010-03-16 10:50:30

您應該始終記錄您的代碼。尤其是在其他人工作或將要處理您的代碼時。也許你還沒有機會處理遺留的未記錄代碼，但它可能是一個真正的痛苦！

關於評論本身，一方面避免被寫評論，因爲它是強制性的，試想幾秒鐘，你會發現事情要告訴你的方法，這東西已經不是在方法名，東西對下一個開發者來說可能並不明顯。解釋你的方法做了什麼，什麼是角落案例，它作爲輸入的期望。

請記住：

始終代碼，如果誰最終維護你的代碼將是一個暴力變態誰知道你活的人。

它適用於評論太:)

來源

2010-03-16 08:23:33

你是否認爲像上面這個例子中的這樣一個無用的javadoc評論會讓精神病患者走開？ – Mnementh 2010-03-16 15:01:01

它更容易保持「自我記錄」的代碼。如果你選擇了好的函數和變量名，那麼保持函數簡短（例如，每個函數只有一個想法的10行），這將有助於保持代碼的目的。而且你不必試着保持評論是最新的 - 唯一比評論更糟糕的是評論是錯誤的！

在InfoQ有一個很好的和最近的各種觀點的總結。

來源

2010-03-16 08:45:35 John

代碼的文檔非常重要。但Javadoc（或類似的工具）不是唯一的，也不是最好的方法。最大的缺點是，Javadoc文檔必須保持最新。如果方法改變了，但描述保持不變，那麼這個文檔可能會比麻煩更多。

爲避免文檔與代碼不同步的問題，請使用代碼進行文檔編制。單元測試顯示您的代碼是如何使用的，並且在代碼中斷言可以確保參數和返回值得到驗證。在一個項目中，我在計算中添加了斷言，這個計算中的概率總是在0和1之間。稍後，這個斷言在一個用例中觸發，並直接指向一個錯誤。

最重要的文檔是一個很好的命名。如果你設置了Frobber，那麼setFrobber就是個好名字。在你的例子中給出的Javadoc沒有給這個命名添加任何內容。 frobIt將是一個不太好的名字，method3會很糟糕。代碼評論應該有助於獲得良好的命名。

如果其他方法不足，應該添加Javadocs和ither文檔。但在這種情況下，您需要注意，本文檔始終是最新的。

來源

2010-03-16 10:02:36 Mnementh

問：應記錄所有方法是強制還是可選？

- 答：強制性。

問：是否有規則來記錄哪些方法？

- 答：所有這些。

問：需要記錄每種方法的優點和缺點是什麼？

答：優點：聰明的人可以花時間專注於代碼編寫，而不是代碼拼寫。代碼很好解釋。代碼可以傳遞給新手。缺點：抱怨。陳舊的評論。

注重質量評論可以避免'代碼是自我記錄'問題。
在getter和setter的情況下，並不是每個get和set都是微不足道的。有時候，這很好。如果不是，評論應該注意這些信息。最好保守，總是比不保守的意見，並不得不廢棄代碼，浪費時間搞清楚。

最後一個例子：Carmack Inverse Square Root code.自我記錄，呃？

來源

2010-03-16 15:20:01

我沒有爭辯說根本沒有文檔，也沒有說所有的代碼都可以寫成自我記錄。你的反例是無關緊要的。 – Sjoerd 2010-03-17 09:19:24

強制方法的文檔

回答

相關問題