Code like this really frustrates me... well maybe 'frustrate' is a bit over the top, but it's something I feel the need to point out:

/// <summary>
/// Customer object
/// </summary>
class Customer
{
    /// <summary>
    /// Customer name
    /// </summary>
    private string Name;

    /// <summary>
    /// Customer age
    /// </summary>
    private int Age;

    /// <summary>
    /// Customer constructor
    /// </summary>
    /// <param name="name">the customers name</param>
    /// <param name="age">the customers age</param>
    public Customer(string name, int age)
    {
        ....
    }
}


Now at first glance you may think this is a simple well designed and well document class.... and that's exactly what it is.  But it's TOO well documented.  The comments are stating the bleeding obvious and are completely useless.  It's a waste of the developers time and energy - it would be much better focusing on the domain problem at hand and reflecting this through the code itself.

Now I must admit I went through a stage in my Software Development career where I commented every little thing like this, but nowadays I try to avoid it as much as possible and rather focus on a well written solution using DDD (Domain Driven Design) and BDD (Behaviour Driven Development).  I feel the methods, variables and classes should be named in such a way that comments are not needed - the code should read in such a way that it makes sense in terms of the domain and is easy to follow without having to rely on comments.  If you find yourself in a situation where you feel you have to explain yourself, this might be an indication you could name your method/variable more appropriately or the design of the system could be improved. 

One thing that is good about the code above though is that is not something like this:

    int x = 0;
    string cNm ;
   
What the bloody hell are 'x' and 'cNm'?? This is where a comment would actually help, or even better a completely new variable name.   I think you should never be afraid to have long explicit variables names, as long as its meaningful and communicates to the developer what its purpose is.  Therefore something like: 'int countOfCustomersThatWereCreatedYesterday'  in my opinion is much better than something like 'int c' or 'int count'.  With the latter two it's never really clear what the 'count' is for.

Two thoughts always spring to my mind when I think about commenting:

1. Comments aren't kept up to date.  As the system evolves, the implementation and requirements change, but the comments do not.
2. If you find yourself writing an inline comment to explain a block of code, this is usually an indication that this piece of code should be in its own method and the method name should explain the code's purpose.

It is for these reasons that I prefer to document my solutions with well designed classes using domain language and supporting tests/specs.  Your tests/specs and code will always be kept up to date, but comments will inevitably get left behind.

---

---