Ndoc在屬性最佳實踐？

Question

我的項目經理上週暗示在類中使用ndoc屬性。這是應該完成的嗎？這是否被認爲是最佳做法？我目前正在擴展我所有的ndoc項目的部分，但我不知道需要多少深入。我當然提供了總結，參數，回報和評論給班級和每個方法，但是做屬性是否也需要ndoc？

Answer 1

公共財產是對外部世界的合同，我認爲他們應該被記錄。

內部屬性將只在相同的程序集中使用，因此您可以避免記錄它們。

受保護的屬性將只用於派生類（內部或公共），因此它們可能需要一些文檔。

私人財產只會在課程本身中使用，所以，再次，你可以逃避它。

請注意，「遠離不記錄它」暗示了我對此的感受：你應該記錄下來。同時，我意識到，有時你需要做的一件事或其他...

也許你應該問這對http://programmers.stackexchange.com

Answer 2

就像任何其他成員一樣，屬性的含義應該被記錄下來。這應該不僅包括屬性的作用或可用的內容，還包括其初始值，特殊情況（例如，不得指定的值;可能導致異常或自動被其他值替換的值），作爲以及在可能的情況下推翻派生階層的財產的影響和目的。

Answer 3

公共屬性一定要始終記錄，您所選擇的文檔工作流程是否使用GhostDoc ，NDoc或其他。當人們使用它時，在Intellisence中會顯示關於公共屬性和方法的XML註釋，所以沒有理由不添加任何內容。即使該屬性的名稱解釋了它所做的事情，但在此有XML註釋以確認這一點非常好。在大量代碼中有很多陷阱，所以讓使用你的代碼的人知道他們沒有走進一個代碼很有禮貌。

私有財產可以走兩條路。我會毫不猶豫地稱之爲特別的最佳做法，因爲看到你必須在課堂上發表的評論，在這一點上你可以簡單地看看它的用法。也就是說，我仍然把私人財產的XML評論，如果沒有人爲我自己。你不可能記得6個月後你在做什麼，並且你可以添加任何結構性評論，這樣可以更容易地從你離開的地方取回。