XML評論：要用還是不用？

Question

我的同事很少（如果有的話）在使用我們的軟件時使用XML註釋（我不能說我更好）。我最近看到了使用它們的好處，但是如果它們正在記錄的代碼是清晰寫入的（表達性/描述性變量/函數名稱，一些在線評論），它們真的值得嗎？

謝謝！

Answer 1

XML註釋對於生成文檔非常有用。如果代碼寫得很清楚，那麼你就不需要評論來幫助你理解代碼。

然而，文檔註釋對類的用戶來說是有用的，因爲它（應該）包含對類或方法功能的描述，而不是對代碼的描述。

Answer 2

XML註釋對於API甚至那些在小組中使用的API都非常有用。

Answer 3

我們發現它很有用，因爲vs自動檢查以確保某些評論在那裏。此外，任何新進入組織的人都知道評論如何工作，我們不必解釋一個新的評論代碼體系。有時我們已經從中生成了文檔，但是對我們來說使用它真的更容易，因爲它爲您填充了很多東西（如某些參數標籤等）

Answer 4

就內部代碼和註釋而言， here's a post由Jeffery Palermo我剛剛閱讀並且必須同意。

總結：許多評論只是減少了可讀性，並且幫助不大，良好的評論可能會非常有用，但會增加維護軟件的成本，甚至會在維護和提供虛假信息時導致嚴重問題。沒有任何設計和命名代碼的替代品。

Answer 5

是不是有一個註釋標記在功能上被忽略，但可以通過一些XSLT進行處理直接轉換爲文檔？評論是好的（我使用它們），但我認爲註釋標記的價值和直接轉換它可以超過使用註釋作爲文檔。因此，總之，使用註釋標籤作爲文檔被他人閱讀，使用註釋來註釋你自己或'幕後'的東西（即'OMG FIX THIS BEFORE THE WORLD EXPLODES！'）

Answer 6

我認爲代碼評論非常重要，特別是在面向公衆的方法和特性方面。除非他知道他可能不知道它的目的的方法的情況下

Linker.Extract(IpoValidator validator, MeanDexIndicator Indicator) 

：人們可能意味着良好時，他們說他們的代碼是描述性的，也許是這樣，但想到新來的傢伙誰看這個的。人們似乎對評論的主要問題是他們不是很有幫助。這是因爲人們寫了不好的評論。你應該談論發生了什麼，而不是它是什麼。我可以看到這種方法是一種提取方法，所以評論如下：

<Summary>Extracts The Fumble <\Summary> 

是浪費能源。以下更好：

<Summary> 
The Fumble needs to be extracted before the bopper can be used. In order for 
extraction to work a validator and indicator need to be provided. Once extracted 
the bopper is available in the property Linker.Bopper. On fail this 
method will raise the CrappedOutException. 
</Summary> 

看到區別？

我傾向於只使用摘要參數和回報，因爲它們都顯示在intellisense中，其他所有內容都像評論一樣，可能會浪費時間，因爲它們並不總是顯示。

至於那個在改變一些東西后拒絕更新他的評論的人。代碼評論應該抓住這一點。我個人使用私人方法和道具兩個XML評論，但那是個人選擇。在公衆面前的方法和屬性？我不是可選的。