Ndoc關於房地產的最佳實踐？

Question

我的項目經理上周暗示要在類中的屬性上使用ndoc。 這是應該做的事情嗎？ 是否認為這樣做是最佳做法？ 我目前正在擴展我正在研究的項目部分的所有ndoc，但不知道我需要進行多深的學習。 我當然已經為類和每個方法提供了摘要，參數，返回值和注釋，但是屬性也需要ndoc嗎？

Answer 1

與其他成員一樣，屬性的含義也應記錄在案。 這不僅應包括屬性的用途或用途，還應包括其初始值，特殊情況（例如，不得分配的值；會引起異常或自動替換為其他值的值），例如以及在可能的情況下覆蓋派生類中的屬性的后果和目的。

Answer 2

我認為公共財產是與外界簽訂的合同，應該將其記錄在案。

內部屬性將僅在同一程序集中使用，因此您可以避免不對其進行記錄。

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

私有屬性將僅在類本身中使用，因此，再次，您可以擺脫它。

請注意，“擺脫不記錄它”建議了我對此的感覺：您應該記錄下來。 同時，我意識到有時您需要做一件事或另一件事...

也許您應該在http://programmers.stackexchange.com上提問

Answer 3

無論您選擇的文檔工作流程是使用GhostDoc，NDoc還是其他工具，都應該始終記錄公共屬性。 當人們使用XML時，會在Intellisence中顯示有關公共屬性和方法的XML注釋，因此沒有理由不在其中添加任何內容。 即使該屬性的名稱說明了它的作用，也很高興在那里有XML注釋來確認這一點。 很多代碼中都有很多陷阱，所以讓使用您的代碼的人知道自己沒有融入其中是有禮貌的。

私有財產可以任意選擇。 我會猶豫地將其稱為特定的最佳實踐，因為看到您必須在課堂上發表的評論，此時您可以簡單地查看其用法。 話雖如此，我仍然將XML注釋放在私有屬性上，如果對其他人而言，那么對我自己而言。 您將永遠不會記住您六個月后的工作，您可以添加任何結構性注釋將使您更容易從上次中斷的地方繼續工作。