doxygen評論在哪裏適合/必要？

Question

我對doxygen等文檔工具沒有太多的經驗，所以我不確定代碼文檔應該如何看。

我應該在類中爲每個成員變量寫doxygen樣式的註釋嗎？或者，如果變量名稱是不言自明的，這是否過度殺傷？

我應該在相應的實現文件中包含標題中的註釋嗎？我猜不是，因爲任何人在一個文件中改變評論就必須在另一個文件中做出相同的改變;但對於實現這些實現的開發人員來說，不必去查閱頭文件就可以知道給定方法的用途。

Answer 1

我應該爲類中的每個成員變量寫doxygen式的註釋 嗎？ 或者如果變量 的名稱是不言自明的，這是否過度殺傷？

這至少是一個樣式問題。不同的人做不同的方式。

我一般都認爲，要麼public或protected應記錄的一切，因爲這是你的類提供的API（protected是你給任何人的API誰去擴展您的類的一部分）。

對於某些方法來說，當方法足夠簡單時，它可能是過度的，像簡單的getter和setter。無論如何，我仍然記錄這些信息，但如果不這樣做，這可能不是什麼大事。但是，如果您不包含任何文檔，請確保將doxygen配置爲輸出所有文檔，而不僅僅是您記錄的字段/方法。否則，未記錄的方法和字段將不會顯示在輸出中。

我應該包括在相應 執行文件 頭的意見嗎？我猜不是， 因爲任何人在 更改註釋一個文件將不得不作出相同的 變化;但是 肯定會方便開發者 的工作執行不到 不得不諮詢頭文件到 知道給定方法的目的。

只寫一次文檔。 doxygen樣式註釋的目的是讓使用該類的人不會有有來查看代碼（頭文件或其他）。他們會查看由doxygen生成的文檔，該文檔將被很好地格式化和鏈接。只要你的文檔註釋是有用的，那麼doxygen輸出可能比通過和查看代碼更容易使用。

Answer 2

之一的doxygen的想法是，你可以只需添加一個<

例如轉換一個簡單的描述性註釋有關成員到文檔註釋

int anUndocumentedVariable;  // This is used for things and stuff 
int aDocumentedVariable;  //< This is used for things and stuff 

所以，如果你懶得解釋變量的使用，使得它Doxygen的友好是一件小事 - 所以真正的問題是「爲什麼不呢？」。

至於何時需要文檔： 如果類，方法和變量名稱寫得很好，那麼代碼應該是相對自我描述的。在以下情況下，評論/文檔是有益的：

• 總結。有時，即使代碼是非常可讀的，對代碼的簡要總結也比代碼更快地閱讀和理解。

• 解釋上下文或更大的圖片。使用或維護您的代碼的人可以計算出「deleteWhenFinished」的含義。什麼是不明顯的是什麼時候/爲什麼要刪除當已完成？如果你自己刪除了對象，你是否需要設置deleteWhenFinished，否則會導致崩潰？等等。或者你可能有一段文字解釋班級的設計，讓讀者快速瞭解它的用途和應該如何使用。

• 解釋爲什麼某些事情是以特定的方式實現的。例如「我們不能在這裏做XYZ，因爲它需要與ABC系統良好地互動。」

• 要解釋任何有用的信息，例如， 「此參數不能爲空」或「您必須在調用此方法之前調用Initialise（）」。

通常人們建議您只需要公共成員的文檔，以便其他程序員更容易閱讀您的代碼。但這是垃圾 - 第一個需要維護代碼的程序員會恨你。而且這個程序員經常會在3個月的時間內成爲你自己！

當然，你永遠不應該浪費時間寫評論沒用：

bool deleteOnCompletion; //< Deletes on completion 

你不應該要問「我應該記錄本」。如果您可以使用像我的AtomineerUtils加載項這樣的工具，可以自動爲您填寫95％的評論正文，如果您隨後更改了代碼，並自動更新了文字，那麼文檔實際上並不會自動更新，不得不成爲一件苦差事。

只是爲最後一個答案添加一個對應點，我幾乎從不使用「外部」doxygen生成的文檔 - 我發現在我的代碼視圖和文檔頁面之間切換時很痛苦。我只需按f12轉到方法的定義並直接從代碼中讀取doxygen/docxml文檔註釋。