在實現文件中包含註釋類聲明

大家都知道更易讀代碼的優點。所以爲了讓我的代碼更具可讀性，我通常在該類的實現文件中包含註釋類聲明。
這樣我不需要瀏覽各種包含目錄去定義。
所以，這是一個很好的做法或只是過度文件？
如果有一些標準技術，請讓我知道。
編輯：
有沒有辦法從Vim中的實現遷移到類聲明？
除了在新緩衝區中打開它。在實現文件中包含註釋類聲明

感謝

來源

2009-11-17 sud03r

不好的想法：大多數好的編輯器允許你從聲明切換到幾個按鍵的定義。檢查vim和emacs的標籤文件並檢查您的fovorite GUI IDE上的選項。 – 2009-11-17 19:27:54

這其實是適得其反，因爲現在你必須修改類聲明時改變位置，而不是兩個，而這些位置中的一個不會通過編譯器進行檢查以捕獲任何不匹配。

此外，在大型且快速發展的項目中，評論總是過時，因此不能被信任。

所有現代的IDE都可以通過很多方式幫助從類實現中獲取類聲明，所有這些都比滾動到文件頂部然後返回更方便。

作爲替代方案，請考慮使用自動文檔工具，例如doxygen。可以告訴Doxygen在文檔中包含整個類的聲明 - 語法高亮，行號和源文件的鏈接。您可以在構建過程中包含doxygen通行證，並始終擁有最新的代碼參考。

來源

2009-11-17 17:59:12 atzz

這不會有很大的幫助，因爲當類定義爲大於一個屏幕，你的同事將不得不向上滾動去申報。現代的IDE在定位聲明方面非常好，所以恕我直言，這是無用的。

有時真正重要的唯一事情是，當您定義函數時，您將訪問標識符置於註釋中。這確實爲試圖理解代碼的人節省了時間。

像這樣的東西就夠了：

//private 
void Car::ReplaceDriver(const std::string & NewDriver) 
{ 

}

來源

2009-11-17 17:44:42 alexkr

ohh yes ..我看到你的觀點..即使很多編輯提供段摺疊，這麼長的評論似乎是無用的，一見鍾情 – sud03r 2009-11-17 17:48:44

是的，如果你的編輯器提供段摺疊，它通常也提供定位聲明。 – alexkr 2009-11-17 17:58:48

如果VI做.. plz讓我知道多數民衆贊成在我需要.. – sud03r 2009-11-17 18:19:14

我認爲它是過度的文檔，從來沒有在別處看過。在修改課程時，註釋會很快失去同步（或者從那裏看你永遠不會確定）。

不知道你使用的是什麼環境，但是在尋找聲明時，我通常使用編輯器的功能（在Mac Xcode和Windows VisualStudio上，你可以右鍵單擊某個東西然後跳轉到它的定義或聲明）。

來源

2009-11-17 18:08:41 Nicholaz

這打破了DRY原理：當您更改聲明時，您必須保留註釋。

它不會幫你讀大量的代碼。

正如他們所說（從記憶）：「如果代碼和評論說不同的故事，他們肯定是錯誤的。「

什麼將幫助是：

確保在頭類聲明是有據可查的和/或非常明確的類使用：這是大多數類的用戶會看首先是因爲這是你的課程的「手冊」（無論是評論還是明確的功能）;
以一種告訴你的意圖的方式來寫這些評論，而不是完全準確的：意圖是它應該做什麼，而不是它做了什麼（如果它是越野車） - 這樣你可以給其他人（或你自己）提供線索ter）修復您的實施中的錯誤，因爲他們可以理解您嘗試執行的操作;
不要在您的定義文件（cpp）中報告您的標題註釋，因爲它會變成redondant！
在定義代碼中寫下注釋，您需要告訴其意圖以及您在哪裏做什麼可能不明顯;
如果可能的話，用實際代碼（函數或類）替換實現代碼中的註釋：您可以經常使用顯式名稱或變量中的操作結果將代碼塊封裝在函數中， - 程序員會比不清楚的註釋更推動執行的代碼...

來源

2009-11-17 18:16:16 Klaim

C++通過要求拆分頭/源打破DRY原則...嗅 – 2009-11-18 09:28:19

我不這麼認爲：聲明和定義顯然是不同的信息（完成彼此）。問題是，爲了識別它的聲明和它的定義，你必須重新輸入至少它的聲明。如果有一種方法可以簡單地使用聲明中使用的名稱，它看起來不會像DRY中斷。 – Klaim 2009-11-20 19:03:33

在實現文件中包含註釋類聲明

回答

相關問題