How important are comments in source code

Intended for: C# Developers

Comments

Comments are vital in our daily job, because as far as we can see create code for yourself is easy; read code from other developer and understand it is often a hell. Moreover, the added value of the XML comments that Visual Studio provides us: are shown in IntelliSense and help other developers to understand what certain methods do, why you crate some properties, ...

Please, take comments in count before start coding. Often we make confusing things (because of a lack of analisys, or because it's the only way out) which is mandatory to comment it intended for other one, even yourself in a few time, will understand it.

For it we have one line comments...
public void CorkBreadMethod(bool entry)

{
     if (entry)
     {
          //Code if entry is true

     }
}

…useful to bring a fast description of what we want to do.

We can use multiple line comments…

public void CorkBreadMethod(bool entry)
{
     if (entry)
     {
     /* Code if entry is true and loren ipsum when the sun goes
     * down and the moon is dark */
     }
}

… they are usefull when the line is too large and is totally neccesary all the text that we introduced. It is very important take this in account, text must be really neccesary; if not we're making dirty code for the next code reader. Watch section about line lenght.

XML Comments

XML comments are very important because they'll be the best help for the user to undestand better our classes and methods. For use them, Visual Studio provides us an automation: before the class, property or method (over the previous line) declaration we will write three times the slash character /// and automatically will be created the neccesary headers for the XML comment:

/// <summary>
/// Class in charge of beign an example
/// </summary>
class CorkBreadClass
{

}

Previously is an example on how to identificate one class using an XML comment. After do it, outside that class you will see as follows:

/// <summary>
/// Method inside CorkBreadClass
/// </summary>
/// <param name="entry">A boolean that represents the entry</param>
/// <returns>5 if entry is true, 0 elsewhere...</returns>
public int CorkBreadMethod(bool entry)
{
     return entry ? 5 : 0;
}

With previous XML comments we have the following results:

As we can see in previous capture, we get back all the previous information inside XML comments, so we gain that people that don't know too much our code or not have access to the source can understand what happend inside.

Unknown

Author y editor