Menu
I'm going through some new code I just wrote and adding NDoc sytle comments to my classes and methods. I'm hoping to generate a pretty good MSDN style document for reference.
In general, what are some good guidelines when writing comments for a class and for a method? What should the NDoc comments say? What should they not say?
I find myself looking at what the .NET framework comments say, but that gets old fast; if I could have some good rules to guide myself, I could finish my docs a lot faster.
411
The documentation also provides the framework in which to place the code. as coding progresses, the code is inserted into the framework already created by the program documentation. Documentation is important to tell other programmers what the program does and how it works.
In comments used to build API documentation, you should:
Explain what the method or property does, why it exists at all, and explain any domain concepts that are not self-evident to the average consumer of your code.
List all preconditions for your parameters (cannot be null, must be within a certain range, etc.)
List any postconditions that could influence how callers deal with return values.
List any exceptions the method may throw (and under what circumstances).
If similar methods exist, explain the differences between them.
Call attention to anything unexpected (such as modifying global state).
Enumerate any side-effects, if there are any.
192
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
