海傢伙,如何使程序評論更有用?
我見過的人,包括在他們的程序註釋..
是它提高程序員間通信 和代碼的可讀性,通過明確程序員 意圖和設想?
應該用技術術語而不是自然語言術語來表達意見嗎?
如何使用評論儘可能有效?
在程序中添加註釋真的是一種很好的做法嗎?
海傢伙,如何使程序評論更有用?
我見過的人,包括在他們的程序註釋..
是它提高程序員間通信 和代碼的可讀性,通過明確程序員 意圖和設想?
應該用技術術語而不是自然語言術語來表達意見嗎?
如何使用評論儘可能有效?
在程序中添加註釋真的是一種很好的做法嗎?
評論只能用於解釋爲什麼的代碼是這樣的。它不應該解釋代碼在做什麼。代碼正在做的是由代碼描述。
這就是說,一些語言有工具,在註釋中尋找特殊字符以生成文檔。 Java就是這樣一種語言。但是這些並不是代碼註釋,因爲它們恰好是語言註釋中使用相同語法的文檔。
評論可用於自動文檔,其他開發人員之間的通信,內存,待辦事項列表或功能的基本說明。請注意,評論應該是補充 - 如果您的代碼需要評論,則需要重新考慮您的代碼。
爲了儘可能提高效率,請爲您的註釋創建一個模板以存在。此外,這不僅可以幫助您閱讀和理解代碼,還可以幫助解析器從您的註釋中爲您創建文檔if他們在整個代碼中都採用一致的格式。
我嘗試和評論每個函數描述在高層次,但確切的方式,功能是什麼。精度應該是這樣的,它不需要讀取函數的主體來理解函數的功能,或者重新實現它,並使其與任何調用它的代碼完美協作。
除此之外,我嘗試保持功能足夠小,以上基本上是所有必要的文檔。
有一段時間,代碼中可能會出現一些不太明顯或奇怪的現象 - 我記錄了這一點。任何不明顯或直覺上不正確的東西,或者你花了一些時間思考的東西都應該記錄下來。
想象一下你有一個記憶問題,並會忘記在一個月內寫這個程序。然後想象你必須回去修復它。您想評論哪些內容以及這些評論如何對您最有用?
首先嚐試編寫代碼,以便人們不用評論即可關注。
最好讓程序自我描述,然後不需要太多評論。
編寫清晰的代碼始終是讓代碼易於理解的第一步。然後,您可以在評論中通過查看代碼來解釋不清楚的部分。
對於我自己,評論解釋了當時我在想什麼。這樣,從現在開始六個月後,當我不記得自己在寫什麼時,我可以用評論來理解。
的評論一些經典用途:
作爲一項規則,如果您發現自己做了一些不明顯的事情,請對其進行評論。
另一種評論方式是先將函數的主體寫爲註釋。然後分開評論並將代碼放在下面。當它終於起作用時,清理並修復註釋。
Ciao!
這似乎是社區wiki的一個很好的候選人 – danben 2010-01-11 03:34:22