C# comments tutorial

Question

I would like to know which one is the best material that I can hand out to my students about "C# comments".

Answer 1

Without a doubt it must be Strunk and White.

Answer 2

Inside VS

Comments are relatively simple.

You can use for single line :

//This is a single line comment

You can use for multiple line:

/*
Multiple lines
*/

For method you can use :

    /// <summary>
    /// This is a description
    /// </summary>
    /// <param name="sender">Description of variable SENDER</param>
    /// <param name="e">Description of variable E</param>

Outside VS

When you go in the Project Property you can output all comments into XML and manipulate them.

Good practice

Comments should not be used to describe WHAT the code do but WHY or HOW if it's not clear.

Answer 3

This Post by Jeff Atwood on his blog Coding Horror goes into the purpose of comments in general. Something you might think is 'duh' really isn't -- especially in the 'real world' when you see comments like the one below:

//Connect to the Database
Db.Connect();

And of course, there's the corollary to that post: Coding Without Comments.

Answer 4

This is quite interesting to do with the xml comments: http://thoughtpad.net/alan-dean/cs-xml-documentation.html

These get read by sandcastle too... :o)

Answer 5

Something that I read a while ago (and have lost track of where) is:

• Beginners comment nothing
• Apprentices comment the obvious
• Journeymen comment the reason for doing it
• Masters comment the reason for not doing it another way

Answer 6

Take a look at this question I asked on SO about code documentation. There's some interesting insight in there that you may wish to repackage.

http://stackoverflow.com/questions/288298/code-documentation-how-much-is-too-much