Skip to content

Latest commit

 

History

History
39 lines (17 loc) · 2.3 KB

Documentation.Guidelines.md

File metadata and controls

39 lines (17 loc) · 2.3 KB

Documentation Guidelines

Write comments and documentation in English

Documents must be written in English (see here).

NOTE Doomen's original document clearly stated that Use US-English. In this document, the US part is deliberately omitted.

Document all public, protected and internal types and members

Documenting your code allows Visual Studio to pop-up the documentation when your class is used somewhere else. Furthermore, by properly documenting your classes, tools can generate professionally looking class documentation.

Write XML documentation with another developer in mind

Write the documentation of your type with another developer in mind. Assume he or she will not have access to the source code and try to explain how to get the most out of the functionality of your type.

Write MSDN-style documentation

Following the MSDN on-line help style and word choice helps the developer to find its way through your documentation more easily.

NOTE Either GhostDoc or Sandcastle Help File Builder can generate a starting point for documenting code with a shortcut key.

Avoid inline comments

If you feel the need to explain a block of code using a comment, consider replacing that block with a method having a clear name.

Only write comments to explain complex algorithms or decisions

Try to focus comments on the why and what of a code block and not the how. Avoid explaining the statements in words, but instead help the reader understand why you chose a certain solution or algorithm and what you are trying to achieve. If applicable, also mention that you chose an alternative solution because you ran into a problem with the obvious solution.

Don't use comments for tracking work to be done later

Annotating a block of code or some work to be done using a TODO or similar comment may seem a reasonable way of tracking work-to-be-done. But in reality, nobody really searches for comments like that. Use a work item tracking system such as Team Foundation Server to keep track of left overs.