|
• When modifying
code, always keep the commenting around it up to date.
•
Comments should consist of complete sentences and follow active language naming
responsibilities (Adds the
element
instead of
The element is added).
•
At the beginning of every routine, XML documentation is used to indicate the routine's
purpose, assumptions, and limitations. A boilerplate comment should be a brief introduction
to understand why the routine exists and what it can do. Refer to the detailed discussion
on XML documentation in this document as well as in the document provided with Visual
Studio .NET.
•
Avoid adding comments at the end of a line of code; end-line comments make code
more difficult to read. However, end-line comments are appropriate when annotating
variable declarations. In this case,
align all end-line comments at a common tab stop.
•
Avoid using clutter comments, such as an entire line of asterisks. Instead, use
white space to separate comments from code. XML documentation serves the purpose
of delineating methods.
•
Avoid surrounding a block comment with a typographical frame. It may look attractive,
but it is difficult to maintain.
•
Prior to deployment, remove all temporary or extraneous comments to avoid confusion
during future maintenance work.
•
If you need comments to explain a complex section of code, examine the code to determine
if you should rewrite it. If at all possible, do not document bad code – rewrite
it. Although performance should not typically be sacrificed to make the code simpler
for human consumption, a balance must be maintained between performance and maintainability.
•
Use complete sentences when writing comments. Comments should clarify the code,
not add ambiguity.
•
Comment as you code, because most likely there won't be time to do it later. Also,
should you get a chance to revisit code you've written, that which is obvious today
probably won't be obvious six weeks from now.
•
Avoid the use of superfluous or inappropriate comments, such as humorous sidebar
remarks.
•
Use comments to explain the intent of the code. They should not serve as inline
translations of the code.
•
Comment anything that is not readily obvious in the code. This point leads to allot
of subjective interpretations. Use your best judgment to determine an appropriate
level of what it means for code to be not really obvious.
•
To prevent recurring problems, always use comments on bug fixes and work-around
code, especially in a team environment.
•
Use comments on code that consists of loops and logic branches. These are key areas
that will assist the reader when reading source code.
•
Separate comments from comment delimiters with white space. Doing so will make comments
stand out and easier to locate when viewed without color clues.
•
Throughout the application, construct comments using a uniform style, with consistent
punctuation and structure.
•
Comments should never include special characters such as form-feed and backspace.
|