Code comments improve the readability of the code that you have developed and they are useful for anyone modifying or maintaining that code. Furthermore, code comments form the basis of auto generated documentation. Great code comments must do the following: Never state the obvious.Write a meaningful comment, use precise wording to describe why.Imagine yourself in the shoes of the developer using this piece of code, what would you want to know?For properties and methods, use active wording such as Set..., Gets... and Specifies... and then explain what it does.List all preconditions for your parameters (can not be null, must be within a certain range and so on).List any post-conditions that could influence how callers deal with return values.List any exceptions the method might 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.Be consistent.Be concise.Make sure that your comments are reviewed.
See the below stackoverflow post for more examples. https://stackoverflow.com/questions/3143324/what-are-best-practices-for-documenting-c-sharp-code-with-xml-comments
|