Free ebook on commenting

Stumbled across ic#code‘s free ebook ‘The fine art of commenting’ this morning, it’s from 2002 but everything still applies, you can download it here.

The book covers commenting in general and not just C#, but in relation to C# here’s the list of the predefined xml tags you can use in comments (something I have to search every time..):

<c> Marks a part of a comment to be formatted as code
<code> As above, but multiline
<example> For embedding examples in comments, usually uses <c>
<exception>* Documents an Exception class
<include>* Includes documentation from other files
<list> A list of <term>s defined by <description>s
<para> Structures text blocks, e.g. in a <remark>
<param>* Describes a method parameter
<paramref>* Indicates that a word is used as reference to a parameter
<permission>* Gives the access permissions to a member
<remarks> For overview of what a given class or other type does
<returns> Description of the return value
<see>* Refers to a member or field available
<seealso>* As above, but displays a ‘See also’ section
<summary> A summary of the object
<value> Describes a property

* validated by the C# compiler

Leave a Reply

Your email address will not be published.