latest Post

Coding Standards and Guidelines: Comments for C#

C# Coding Standards and Guidelines: Comments

1. All source code must include the following comments at the very top:

/********************************************************
*Author:
*Date:
*Description:
*Revision:
********************************************************/

2. All comments should be written in English(like in U.S. English).

3. Comments lines should begin with // indented at the same level as the code they are documenting.

4. Do not use /* … */ blocks for comments.


5. Source code comments should be written in clear, concise, English sentences.

6. Comments should be included in source code to indicate what the code does and to break up large sections of code.

7. Comments should not be used to teach the reader how to program. Assume the reader knows as much about the programming language as you do.

8. Comments should not be used to describe obvious code. The purpose of comments is to increase your code readability. Often using good variable and method names make the code easier to read than if too many comments are present.

9. Never “comment out” code without also including a description of why you did so. If the code isn’t necessary it should be deleted.

10. Do not use “clutter” comments, such as an entire line of asterisks. Instead, use a single blank line white space line to separate comments from code.

11. Do not “draw flower boxes” around comments using rows of asterisks or other characters.

12. Comments should not include humorous remarks. Your comments may seem funny to you when you type them, but they won’t to the person who has to understand and fix your code during a late-night debugging session.

13. Include Task-List keyword flags to enable comment filtering.

Example: // TODO: Place Database Code Here

14. Always include <summary> comments. Include <param>,
<return> and <exception> comment sections where applicable

15. Always add CDATA tags to comments containing code and other embedded markup in order to avoid encoding issues.

16. Indent comment at the same level of indentation as the code you are documenting.

17. All comments should pass spell checking. Misspelled comments indicate sloppy development.

About Mallikarjun A

Mallikarjun A
Recommended Posts × +

0 comments:

Post a Comment