我目前正在開始使用doxygen來記錄我的源代碼。我注意到，語法非常重，每次修改源代碼時，我也需要更改註釋，並且我真的有這樣的印象：在源代碼中進行的每個更改都會修改註釋。Doxygen，維護太重？
你有一些技巧來有效地記錄我的源代碼嗎？
doxygen是否存在一些編輯器（或現有編輯器的插件）？
PS：我在C/C++項目。
難道你覺得Doxygen的語法很難嗎？或者事實上你現在必須評論所有的功能。
如果是前者，可能會有不同的工具更適合您的編碼風格。請記住，Doxygen支持多種評論風格，所以試驗，直到找到你喜歡的一個。
如果是後者，那就強硬一點。作爲一個良好的編程習慣，每一個面向公衆的功能應該有一個評論標題解釋：
無論您使用哪種文檔工具，情況都是如此。
我的重點提示：避免太多評論的誘惑。描述你所需要的，而不是更多。 Doxygen給你很多標籤，但你不必全部使用它們。
至於你的問題：的Doxygen有一些配置選項來觸發警告，當意見不代碼相匹配。您可以將其集成到您的構建過程中，並掃描Doxygen輸出以獲取任何警告。這是我發現在代碼和評論中發現偏差的最佳方式。
除了返回代碼之外，我還推薦函數可以引發的任何異常。 – mklauber 2011-08-10 19:50:51
你想介紹一下最後一部分（關於你的問題）嗎？ – 2014-10-03 01:26:20
我覺得你回到你留下的評論，5分鐘評論一個類會在3個月的時間，當類需要由原作者以外的其他人（有時由原作者）改變將花更少的時間去掌握。
我第二次提到大衛提到的文檔支持，在eclipse中重構參數名稱時，它將重命名文檔部分中的參數。我不確定我會希望它自動地做任何其他事情。
「每當我修改源代碼時，我也需要更改註釋」可能是您記錄太多。你應該只需要改變一個函數的文檔，如果改變它需要你以某種方式改變每個調用者（或者如果沒有真正改變，至少檢查以確保他們不依賴於過時的行爲），如果你正在引入新的調用者將依賴的新功能。所以理論上它不應該是一個巨大的開銷。小的改變，比如函數中的優化和錯誤修正，通常不需要記錄。
對代碼的新功能和早期階段使用非文檔化註釋。當您發現您的代碼已準備好發佈時，您可以更新文檔。同時避免重複參數或函數名稱。
這實際上取決於您在文檔中放置了多少信息。
由於單元測試，我的函數通常比較小，因此文檔相對較小。另外，當記錄類本身時，我總是有一小段代碼來顯示類應該如何使用。我發現那些是最難維護但值得的，所以你不會讓小孩子問你如何使用課堂。
提示：
當你在6個月的時間內編輯你的代碼時，你會很高興......
對於您使用評論的方式或您的開發方式存在嚴重錯誤。
Doxygen註釋用於接口的外部/內部文檔。如果您的界面變化非常快，那麼您應該先坐下來思考架構佈局。
如果您使用doxygen來記錄函數的內部流，那麼您應該重新考慮這種方法（即使這樣，這些註釋也不應該改變那麼多）。當你有一個計算某個值的函數，那麼評論/// Calculating xy using the abc algorithm肯定是不應該每天都在改變的東西。
我同意 - 編程中的封裝也適用於註釋 - 代碼的調用者不應該關心*你怎麼做你的類/函數做了什麼，但是他們確實在乎它做了什麼。你應該能夠在不改變.h文件中的東西的情況下改變你的函數的實現（.cpp/.c文件中的東西）（我假設你把doxygen註釋放在頭文件中，但是原理不管你把它們放在哪裏都保持不變）。 – Thomi 2010-03-09 15:08:04
在我的專業軟件體驗中，每次修改源文件時，都必須輸入描述更改的註釋。這些更改註釋通常不在Doxygen註釋區域（除非對接口進行更改）。
我強烈建議你讓你的代碼評論一個習慣。這不僅適用於其他人必須維護或協助您使用代碼的情況，還有助於您放棄源文件一段時間（例如管理層告訴您切換項目時）。我發現編寫評論，因爲我的代碼可以幫助我更好地理解算法。
如果以下風格適合您的需求，請自行判斷。這是C-affine壽，但也許你可以從中得出足夠的結果。
///\file
/// Brief description goes here
bool /// @retval 0 This is somewhat inconsistent. \n Doxygen allows several retval-descriptions but
/// @retval 1 will not do so for parameters. (see below)
PLL_start(
unsigned char busywait, ///< 0: Comment parameters w/o repeating them anywhere. If you delete this param, the
/// comment will go also. \n
/// 1: Unluckily, to structure the input ranges, one has to use formatting commands like \\n \n
/// 2-32767: whatever
int param) ///< 0: crash \n
/// 1: boom \n
/// 2: bang!
{
/**
* Here goes the long explanation. If this changes frequently, you have other more grave problems than
* documentation. NO DOCUMENTATION OF PARAMETERS OR RETURN VALUES HERE! REDUNDANCY IS VICIOUS!
* - Explain in list form.
* - It really helps the maintainer to grok the code faster.
*
*@attention Explain misuses which aren't caught at runtime.
*
*@pre Context:
* - This function expects only a small stack ...
* - The call is either blocking or non-blocking. No access to global data.
*
*@post The Foobar Interrupt is enabled. Used system resources:
* - FOO registers
* - BAR interrupts
*/
/**@post This is another postcondition. */
}
除了Doxygen我想你應該看看Code Rocket。
它實際上通過拖拽實際的代碼和它們包含的註釋來記錄你的方法「內部」發生了什麼 - 因此不僅限於函數的註釋頭部，它可能會過時實際的功能內容。
它會自動爲您提供方法內容的流程圖和僞代碼可視化形式的文檔。
使用Doxygen的優勢 - 它會生成類和方法的描述，而無需添加註釋（只是不會默認 - 設置EXTRACT_ALL = YES）。
我沒有記錄每個參數，因爲我認爲他們的名字應該爲他們做（*）。
我反對大多數人推薦的自動記錄插件，因爲他們創建了通用註釋，您將不得不維護。
我希望評論有意義 - 如果我看到評論，它會脫穎而出，我會注意。
（*）例外情況是當公共代碼中的接口非常穩定時，有些人會從其他解釋中受益，即使那樣我也會盡量避免記錄。
文檔很容易失去同步，也許最好的方法是以敏捷的方式進行評論。不同步的評論可能造成更多的傷害而不是更好的。 – 2010-03-09 09:48:26
你在用什麼IDE？ Eclipse CDT具有doxygen支持（即使很尷尬），並且如果您要求它將爲您創建空的doxygen註釋。 – 2010-03-09 09:53:05
我正在使用vim。我傾向於避免使用Eclipse CDT，因爲代碼完成非常慢（我聽說他們製作了一些程序...）。我不在乎使用任何其他編輯器記錄我的代碼（如果親和力更多）。 – Phong 2010-03-09 09:57:40