2010-01-11 54 views
2

海傢伙,如何使程序評論更有用?

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

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

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

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

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

+4

這似乎是社區wiki的一個很好的候選人 – danben 2010-01-11 03:34:22

回答

7

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

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

+2

或者應該由代碼來描述......評論無法替代可讀的代碼。 – yodie 2010-01-11 03:35:12

+0

要補充的是:當評論描述*代碼在做什麼時,你可能會冒兩個不同步的風險。我讀過的評論不反映代碼,我不知道代碼或評論是否有誤。 – 2010-01-11 03:39:23

+0

+1爲「爲什麼」。我還包含用於編寫代碼的任何參考資料的URL,例如特定的解決方法。 – AUSteve 2010-01-11 04:42:50

2

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

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

1

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

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

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

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

0

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

1

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

2

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

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

的評論一些經典用途:

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

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

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

Ciao!

相關問題