I was reading the
book about debugging and there was a very important part about commenting... I have summarized the following points:
Always document:
- your assumptions
- your approach
- the reasons why you have choosen for this approach
For each function or method:
- what does the routine?
- which assumptions have you made?
- what does every in- and output param contains?
- what are all the posssible return values or the routine?
- document every exception which is directly thrown in this routine
Always document bugfixes which you have made during development. (when available write down the bug number or reference where more information can be found about the bug/solution)
Always throw commented code away, because it is not clear what the meaning is of this in five years...
Always improve your code when you think "This is a hack"
Xml Commentscopied from winnershtriangleexception: The exception tag allows a method's exception handling to be documented. The cref attribute allows the namespace of the exception handler to be included. Example:
Throws an exception if the customer is not found.permission: The permission tag can be used to describe any special permissions a specific object needs. The object to which the permission refers is included as the cref attribute. Example: Class needs to write to the file system, ensure user has appropriate access.
