Comments and Embedded Documentation – The Expert Software Guy

Use Single Line Comments.

All comments shall be written in US English.

Use “flowerbox” comment blocks.

Use these at the class level, css file, skin file, js files above the declaration.

Example

        // ************************
        // Comment block
        // ************************

Use inline comments

Use inline-comments to explain assumptions, known issues, and algorithm insights.

Use comments to explain complex workflows.

In the case of complex code or “hard to follow” code separate key sections with double space and start it with a comment of a sentence that describes the intent of the code. If you need more that 1 sentence, consider simplifying the code.

Do not use inline-comments to explain obvious code.

Do not assume that “well written” code is self-documenting. Although this is a noble belief the reality is that it is subjective and opportunity for failure. However, code that it obvious does not need to be commented. The exception is in the case where “obvious code” is out of place given its surroundings.

Use #region to group non-public members.

If a class contains a large number of members, attributes, and/or properties, put all non-public members in a region. Preferably, use separate regions to split-up the private, protected, and internal members, and a region to hide all fields. It is also allowed to use the #region construct for separating the smaller auxiliary classes from the main class.

Use XML tags for documenting types and members.

All public and protected types, methods, fields, events, delegates, etc. shall be documented using XML tags.

Example

        /// <summary>
        /// This is the summary
        /// </summary>
        /// <param name="TrackingNumber"></param>
        /// <returns>
        /// This is the description of the return
        /// </returns>

Using these tags will allow IntelliSense to provide useful details while using the types. Also, automatic documentation generation tooling relies on these tags.

Section tags define the different sections within the type documentation.

SECTION TAGS	DESCRIPTION	LOCATION
`<summary>`	Short description	type or member
`<remarks>`	Describes preconditions and other additional information.	type or member
`<param>`	Describes the parameters of a method	method
`<returns>`	Describes the return value of a method	method
`<exception>`	Lists the exceptions that a method or property can throw	Method, event or property

`<value>`	Describes the type of the data a property accepts and/or returns	property
`<example>`	Contains examples (code or text) related to a member or a type	type or member
`<seealso>`	Adds an entry to the See Also section	type or member
`<overloads>`	Provides a summary for multiple overloads of a method	first method in an overload list.

Inline tags can be used within the section tags.

INLINE TAGS	DESCRIPTION
`<see>`	Creates a hyperlink to another member or type
`<paramref>`	Creates a checked reference to a parameter

Markup tags are used to apply special formatting to a part of a section.

MARKUP TAGS	DESCRIPTION
`<code>`	Changes the indentation policy for code examples
`<c>`	Changes the font to a fixed-wide font (often used with the <code> tag)
`<para>`	Creates a new paragraph
`<list>`	Creates a bulleted list, numbered list, or a table.
`<b>`	Bold typeface
`<i>`	Italics typeface

Exception:

In an inheritance hierarchy, do not repeat the documentation but use the <see> tag to refer to the base class or interface member.

Exception:

Private and nested classes do not have to be documented in this manner. If in doubt comment out.

Don’t use angle brackets in XML comments

Angle brackets are protected in XML. If you add this to the content of XML comments, it will break the comments.