評論C代碼，標題和源文件

Question

我正在尋找一個「最佳實踐」來記錄我的C代碼。就像在任何項目中，我有一些頭文件「.h」和各自的源文件「.c」

在頭文件中你放什麼樣的評論？並在源文件？ 問題出現了，因爲我很好地評論了我的頭文件，所以c文件看起來像一團糟。

您在保持代碼良好評論的最佳做法是什麼？

Answer 1

頭文件用於代碼用戶。所以在那裏我記錄了接口：如何使用它，先決條件和後置條件等等。

該.c文件用於維護人員。在那裏，我記錄了實現：事情是如何在內部工作的，以及它們爲什麼以這種方式工作。

Answer 2

如果這是一個個人項目，我建議有很多coding standards你可以採用（幾乎所有包括如何佈置評論部分）。

如果沒有，我會想象你的公司/ teaam /項目已經有一些東西在使用。

Answer 3

我建議採用由Doxygen這樣的工具強加的約定。然後，不僅僅是代碼註釋，您還可以生成HTML/PDF/Latex等文檔，併爲您提供良好的約定。

與托馬斯同意關於cpp文件

Answer 4

源文件，我建議你創建的文件頭和函數頭註釋模板。

對於文件標題註釋，您應該對文件，函數名稱，作者，創建日期和記錄修改的歷史進行簡要說明。

包含函數頭，可以解釋函數的邏輯和目的以及各種參數。請確保任何複雜的邏輯或與常見行爲的偏差均通過評論充分記錄。