Free ebook on commenting

Stum­bled across ic#code’s free ebook ‘The fine art of com­ment­ing’ this morn­ing, it’s from 2002 but every­thing still applies, you can down­load it here.

The book cov­ers com­ment­ing in gen­er­al and not just C#, but in rela­tion to C# here’s the list of the pre­de­fined xml tags you can use in com­ments (some­thing I have to search every time..):

<c> Marks a part of a com­ment to be for­mat­ted as code
<code> As above, but mul­ti­line
<exam­ple> For embed­ding exam­ples in com­ments, usu­al­ly uses <c>
<excep­tion>* Doc­u­ments an Excep­tion class
<include>* Includes doc­u­men­ta­tion from oth­er files
<list> A list of <term>s defined by <description>s
<para> Struc­tures text blocks, e.g. in a <remark>
<param>* Describes a method para­me­ter
<paramref>* Indi­cates that a word is used as ref­er­ence to a para­me­ter
<per­mis­sion>* Gives the access per­mis­sions to a mem­ber
<remarks> For overview of what a giv­en class or oth­er type does
<returns> Descrip­tion of the return val­ue
<see>* Refers to a mem­ber or field avail­able
<seeal­so>* As above, but dis­plays a ‘See also’ sec­tion
<sum­ma­ry> A sum­ma­ry of the object
<val­ue> Describes a prop­er­ty

* val­i­dat­ed by the C# com­pil­er

Liked this post? Why not support me on Patreon and help me get rid of the ads!