評論你的代碼的重要性

Question

你如何解釋你的團隊配合評論他們寫的代碼的重要性？我知道一些編寫片段式評論的編碼員，而其他人會留下很多預期的內容，當你閱讀評論時你期望什麼？

Answer 1

如果您正在編寫的語言不是人類可讀的，我建議您使用非常詳細的方法和過程級別註釋。

如果您正在編寫的語言是人類可讀的（C＃，VB等），我建議您在方法級別使用稍詳細的註釋並在過程級別使用最少的註釋。

Answer 2

有一些最低：

1. 所有的函數和類應該評論
2. 的try/catch和異常處理是更好地加以註釋
3. 常量硬代碼編碼應該是絕對
4. 虛擬物體和虛擬類以及TO-DO部分應該被註釋
5. 當您從URL獲取代碼時，應該在評論中引用地址以便進一步考慮n和侵犯版權的問題
6. 還承諾到版本控制系統應該有很好的註釋

雖然意見應保持在最低限度，也沒有必要評論for循環定義時，很明顯， 我通常爲我的程序員設置基本規則，當它定義良好時，他們堅持使用它

Answer 3

在編寫不直觀的代碼時編寫註釋。實際上沒有理由評論只是迭代數組的方法，但是當您修復一個錯誤或必須一起破解某個問題才能解決問題時，最好有一個註釋，以便您可以在6個月後快速瞭解該代碼（以及不意外撤消它）。

Answer 4

你是什麼意思的評論代碼？ 實際的代碼或函數標題？

如果你真的在談論代碼，這是一個失敗的原因。你需要讓他們編寫可讀的代碼並將其分解成有意義的塊。評論不好的代碼並沒有把它變成好的代碼，它只是留下不一致的混亂。對於標題文檔，你必須讓他們捕捉重要的東西（例如，驚喜，指令）並妥協一些微不足道的事情（列出所有參數，重複簽名的功能）。人們討厭記錄函數，因爲大部分工作都花在編寫瑣碎的文本上，這些文本幾乎影響了你的智能（例如，getHandleToFile（），「這會得到文件的句柄」）。由於實際上有比預期更少的重要細節，因此他們會感到驚喜，並且將更有可能將投入投入到這些特定情況中。

Answer 5

• 在方法和類中包含文檔生成註釋。
• 不要評論每一行。
• 如果您正在做一些預期的或代碼中不明顯的事情，請解釋說明原因。

Answer 6

我認爲如果你正在編寫其他人可能會有一天需要遵循的代碼，那麼謹慎地留下關於正在做什麼的好評。如果你只是爲自己寫點東西，那麼傾向是很小的，或者根本沒有。這就是說，我已經有了「不那麼奢侈」的必須返回到我8年前寫的代碼，並沒有充分評論，用我不再使用的語言（ASP類），我可以告訴你，我希望我已經留下了更多評論！

Answer 7

在評論中最重要的事情是說實話。我一直在調查一個錯誤的次數，僅僅是爲了找到一段「不太明顯」的代碼，還有一條評論說它應該和它所做的相反。誰贏？你決定...

在一個相關的說明，任何比它正在記錄的部分更長的評論是通常太長。

Answer 8

最好的評論總是簡潔，用幾句話。它應該說在代碼中不明顯。我看到一些明顯的人，因此無用的評論，如：

if x==0 //if x equals 0 then... 

哦真的嗎？！這只是「污染」了代碼，因爲除非你正在學習如何編程，否則它是無用的。

即使代碼只是你的，你應該寫評論，就好像你正在與另一個完全不知道它的程序員分享它。通過這種方式，您可以確保您始終能夠理解它，並且長期來說，如果有人出現並選擇了該代碼，那麼該人員將能夠理解並擴展/使用它。

我看到評論作爲可重用性的提升。與其他程序員一樣，我期望通過一個簡單而簡明的評論來完整理解代碼塊。

Answer 9

我嘗試評論我的大部分公共方法和類，並且在那些註釋中，您可以閱讀該方法的作用，參數的含義以及輸出的內容。

我也有時會在我的方法中放置註釋，但是，我不評論我在做什麼，但爲什麼我這樣做。