如何使程序評論更有用？

Question

海傢伙，

我見過的人，包括在他們的程序註釋..

• 是它提高程序員間通信 和代碼的可讀性，通過明確程序員 意圖和設想？

• 應該用技術術語而不是自然語言術語來表達意見嗎？

• 如何使用評論儘可能有效？

• 在程序中添加註釋真的是一種很好的做法嗎？

Answer 1

評論只能用於解釋爲什麼的代碼是這樣的。它不應該解釋代碼在做什麼。代碼正在做的是由代碼描述。

這就是說，一些語言有工具，在註釋中尋找特殊字符以生成文檔。 Java就是這樣一種語言。但是這些並不是代碼註釋，因爲它們恰好是語言註釋中使用相同語法的文檔。

Answer 2

評論可用於自動文檔，其他開發人員之間的通信，內存，待辦事項列表或功能的基本說明。請注意，評論應該是補充 - 如果您的代碼需要評論，則需要重新考慮您的代碼。

爲了儘可能提高效率，請爲您的註釋創建一個模板以存在。此外，這不僅可以幫助您閱讀和理解代碼，還可以幫助解析器從您的註釋中爲您創建文檔if他們在整個代碼中都採用一致的格式。

Answer 3

我嘗試和評論每個函數描述在高層次，但確切的方式，功能是什麼。精度應該是這樣的，它不需要讀取函數的主體來理解函數的功能，或者重新實現它，並使其與任何調用它的代碼完美協作。

除此之外，我嘗試保持功能足夠小，以上基本上是所有必要的文檔。

有一段時間，代碼中可能會出現一些不太明顯或奇怪的現象 - 我記錄了這一點。任何不明顯或直覺上不正確的東西，或者你花了一些時間思考的東西都應該記錄下來。

想象一下你有一個記憶問題，並會忘記在一個月內寫這個程序。然後想象你必須回去修復它。您想評論哪些內容以及這些評論如何對您最有用？

Answer 4

首先嚐試編寫代碼，以便人們不用評論即可關注。

Answer 5

最好讓程序自我描述，然後不需要太多評論。

Answer 6

編寫清晰的代碼始終是讓代碼易於理解的第一步。然後，您可以在評論中通過查看代碼來解釋不清楚的部分。

對於我自己，評論解釋了當時我在想什麼。這樣，從現在開始六個月後，當我不記得自己在寫什麼時，我可以用評論來理解。

的評論一些經典用途：

• 解釋爲什麼代碼是不是在最明顯的方式完成 - 如與使用怪異或舊的方式談論系統的連接。
• 解釋什麼樣的代碼可能會調用這個代碼 - 比如在龐大而複雜的系統中。您可以添加顯示可能需要調用此代碼的示例。
• 記錄當前編碼實踐的例外情況 - 例如未被重構爲使用當前系統的遺留代碼。

作爲一項規則，如果您發現自己做了一些不明顯的事情，請對其進行評論。

另一種評論方式是先將函數的主體寫爲註釋。然後分開評論並將代碼放在下面。當它終於起作用時，清理並修復註釋。

Ciao！