Comments

General

Comments should be used to clarify code, state function, and ease the creation of documentation. Good code is readable without a lot of comments, but providing document comments for the methods will make it easier for others to use the code.

Always:

  • Include the license agreement in comments at the beginning of ALL source code files. (*.cs, *.sql, *.xslt)
  • Use XML document comments for *every* class and method.
  • Use comments to explain what your code is doing
  • Use comments ABOVE the code it's describing.

Never:

  • Leave code commented out in source.
  • Omit descriptions for elements in the document comments.

I recommend Jeff Atwood's post on commenting: http://www.codinghorror.com/blog/archives/001150.html

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-Share Alike 2.5 License.