Ndoc on properties best practice?

Question

My project manager last week hinted at using ndoc on properties within a class. Is this something that should be done? Is it considered best practice to do this or not? I am currently expanding all my ndoc for the section of a project that I am working on but do not know how deep I need to go with it. I have of course provided summaries, params, returns and remarks to the class and each method but do properties require ndoc too?

Answer 1

Public properties are a contract to the outside world I think they should be documented.

Internal properties will only be used in the same assembly so you could get away with not documenting them.

Protected properties will only be used in derived classes (internal or public) so they might be in need of some documentation.

Private properties will only be used in the class itself so, again, you could get away with it.

Note that "getting away with not documenting it" suggests the way I feel about this: you should document. At the same time I realize that sometimes you need to do one thing or the other...

Perhaps you should ask this on http://programmers.stackexchange.com

Answer 2

Just like any other members, the meaning of properties should be documented. This should include not only what the property does or what it can be used for, but also its initial value, special cases (e.g. values that must not be assigned; values that would cause an exception or automatically be replaced with other values), as well as possibly the ramifications and purpose of overriding the property in a derived class where this is possible.

Answer 3

Public properties should definitely always be documented, whether your chosen documentation workflow uses GhostDoc, NDoc, or whatever. XML comments on public properties and methods show up in Intellisence when people use it, so there's no reason to not add something there. Even if the name of the property explains what it does, it's very nice to have XML comments there to confirm that. There are plenty of gotchas in plenty of code, so it's courteous to let the people who use your code know they're not walking into one.

Private properties can go either way. I'd hesitate to call it a particular best practice since to see the comments you have to be in the class, at which point you can just look at its usage trivially. That said, I still put XML comments on private properties, if for nobody else then for myself. There's no way you will remember what you were doing 6 months from now and any structural comments you can add will make it easier to pick up where you left off.