評論標準C

Question

我與喬治亞理工學院的一個名爲太陽能夾克的團隊合作，我們一直在進行「評論性危機」。我們有很多成員畢業，留下無評論的代碼。我正在尋求實施評論標準，所以這不會發生，我需要一些建議，以確保我涵蓋了所有的基礎。

我要的是以下功能：

• 一個統一的地方，在這裏你可以查看每一個功能的描述， 其中包括，參數，返回類型，代碼的一般 描述。 （從代碼中的註釋生成）

• 在代碼本身中，逐行（或接近）描述。

有什麼建議我可能會遺漏什麼嗎？是否有任何程序可以自動生成代碼編譯？我怎麼能讓程序員更容易？

Answer 1

你的描述讓我想起了Doxygen。它有一個註釋代碼中所有實體的格式，包括函數，參數，變量，... 它可以用來強制所有事情都通過檢查Doxygen生成的警告來記錄。它以不同格式（如HTML，Latex，PDF等）中的源代碼生成完整文檔...

許多IDE都知道Doxygen標籤，並且可以與Doxygen集成以幫助開發人員評論代碼。

這裏的Doxygen註釋的例子：

/** 
* @brief This function does blah blah. 
* @param test blah blah parameter. 
* @return 0 if blah blah passed. 
*/ 
uint32_t TestFunction(uint32_t test) 
{ 
    return 0; 
} 

Answer 2

• 強制良好的編碼習慣。變量名稱和方法標題應該是描述性的，並專注於他們正在執行的任務。例如，如果您有交換兩個元素的方法，則調用它swap()就足夠了。

• 使用文檔生成工具，如Doxygen或Sphinx。

• 感覺鼓勵使用其他API，如Java 7 API作爲易讀性指南，以及做什麼（或不做）。

我也許應該強調的是，太多文檔可以是非常分散注意力。讓程序員 - 他們的軟件在做什麼的專家 - 爲了文檔的緣故給出高級概述。如果他們想要或必須，那麼讓他們按自己的條件解釋複雜或複雜的代碼。

Answer 3

在我的新工作中，我們儘量避免最大限度地使用評論。代碼應該是自我記錄的。一些小小的評論允許使用棘手的代碼或錯誤修復等，但是日常編程根本不包含任何評論。

我們使用代碼審查會話，以便所有團隊成員都可以閱讀和研究新代碼，如果它不乾淨並且易於閱讀，則會進行重構。通常，包括局部變量來命名錶達式，不重用變量和爲常量文字添加#defines來完成這項工作。

Answer 4

對代碼的逐行評論聽起來很可怕。

• 您需要在函數的開始處註釋以確定它的功能。
  • 如果參數等不明顯，應該討論。
  • 否則，它應該儘可能簡短，最好只有一行。
  • 如果功能比較複雜，可能需要更大的評論;使用判斷。
• 您通常需要一個包含公司或項目的許可證和版權標識的文件頭註釋，以及關於文件總體用途的註釋。
• 你應該記錄變量定義（它應該主要是static變量;你不使用全局變量，是嗎？）。
• 您可能需要評論函數中的代碼段落，最好使用簡短的（一行）註釋。
• 有時候，您需要記錄非顯而易見的或模糊的（可能參考了相關的錯誤報告）。
• 除了局部變量定義之外，您應該很少需要尾註釋。

否則，代碼應該在很大程度上解釋自己，渲染評論是多餘的。

請注意，沒有描述當前代碼的評論是令人討厭的。只有在昨天，我刪除了在1990年–中清楚添加的評論，日期在評論–中描述了1990年的現狀，當時一個特定函數模擬'可變參數'。該代碼早已更新，因此該函數被視爲具有7個固定參數;當不需要時，最後四個可以爲空。所以，評論不再準確，但十年或更長。它去。爲什麼沒有人注意到它？可能是因爲沒有其他人在沒有導師的情況下第一次閱讀該文件來引導他們過去錯誤的評論。或者，也許是因爲評論已經足夠遠離該功能（評論和它被錯誤描述的功能之間存在一個完全獨立的，儘管很小的功能）。所以，30條評論（不準確）終於落到了天空中的位置。

還要注意，專家需要什麼和新手對同一段代碼的需求可能會大不相同。你必須對評論的級別進行判斷，但是我建議在散文方面對散文作出錯誤判斷，因爲當修改代碼時，兩個描述中的一個將不會得到適當的維護，並且可能性將會是不被維護的評論。誤導性的評論對於新手來說比專家更可怕！所以，請確保您不會因爲沒有任何可避免的評論而收到不準確的評論。