在來源或標題文件中發表評論

Question

這是一個非常簡單的問題，我很驚訝我沒有發現任何其他地方。我想知道哪些評論應該或不應在標題/源文件。如果在頭文件和源文件中聲明，那麼這將是redondant或必需的。到目前爲止，我已經做了這樣的：

的main.c或main.cpp中

int main() 
{ 
    // Comments to describe what happens in main 
} 

foo.h中

// Comments for documentation and which gives information about the function itself 

/** 
* \fn void aFunction(void) 
* \brief This function is a function 
*/ 
void aFunction(void); 

foo.c的或Foo.cpp中

void aFunction(void) 
{ 
    // Comments to describe and explain what happens within this function 
} 

• 沒有太多的評論中主力，只是描述基本上什麼是所謂的功能，爲什麼
• 在頭部，僅評論來形容函數本身;參數，簡要，返回等
• 在源代碼中，只有註釋來描述發生了什麼功能;環，條件等

這就是我所知道的。主，源或頭文件中是否需要更多評論？我要補充我通常只把在源頭太的意見，這樣的：

的foo.c或Foo.cpp中

/** 
* \fn void aFunction(void) 
* \brief This function is a function 
*/ 
void aFunction(void) 
{ 
    // Comments to describe and explain what happens within this function 
} 

我知道這是一種主觀的，但也我認爲評論是一門藝術，而藝術仍然是主觀的，需要技術性。

Answer 1

C文件應包含您在編寫代碼時隨處寫入的常見註釋。它做什麼和爲什麼。通常在每一行的結尾，除非需要更廣泛的評論。 H文件可以包含一個簡短的最小值，解釋函數作爲參數以及它返回的內容。或者，它也可以包含關於如何使用該功能的完整文檔。如果頭文件中沒有提供完整的文檔，則必須單獨編寫它。注意：爲了生成某種無用的「文檔」文件，幾行Doxygen廢話不算作完整的文檔。

H文件記錄了函數做了什麼以及如何使用它，而沒有提及實現細節。重要的是要認識到，h文件應該是相應c文件（或庫）的完整獨立界面。調用者需要注意的所有類型和依賴項（包括）應該存在於h文件中。

這包括任何預處理和後處理條件：在調用函數之前需要執行哪些操作？該功能使用了哪些資源？它是否讓任何處理/文件/資源​​打開，以後需要清理？它是否改變了一些全球狀態？等等

相應的c文件不一定會提供給用戶，用戶也不需要閱讀c文件以瞭解應該如何使用那些函數。一切都應該從h文件中明顯看出來。

Answer 2

就我個人而言，我的經驗法則是儘可能避免評論。

要做到這一點，儘可能;

• 使在由類型名，常量枚舉值，函數名，變量名等的適當選擇頭自我記錄聲明;
• 使函數定義儘可能小而簡單，儘可能清楚它們如何執行它們的操作。通過適當選擇變量名稱，本地類型等，儘可能地將函數作爲自記錄文件。將大函數分解爲一組較小的函數，並儘可能使所有函數成爲自記文件。
• 選擇文件名（用於標題和編譯單元），因此函數和聲明的分組是顯而易見的。

然後僅在需要解釋某些通過查看代碼本身而不明顯的內容時才使用註釋。例如，最好解釋爲什麼代碼執行某些操作，並允許代碼本身描述HOW。如果一個函數具有特定的前提條件（被調用時被假定爲真的東西）或後置條件（當滿足前提條件時函數返回時，函數保證爲真的東西），那麼可以在註釋中描述它們。

我不使用註釋來追蹤版本歷史（這是版本控制系統的用途）。

有時，以簡單明瞭的方式編寫代碼是不可能的。在這些情況下，需要評論。但是評論中的問題（例如忘記更新它們，因此它們不再與代碼對應）非常重要，所以最好努力工作，以便代碼儘可能好地描述自己。

這也意味着努力工作以避免隱晦的代碼。不要寫25個副作用的陳述。縮進代碼，以便與實際結構一致（代碼格式化程序可以幫助完成此操作）。儘可能避免使用宏（因爲它們可以做與範圍不一致的事情）。