Documenting the code

If a new framework is developed in your company, and you are going to use it, without proper documentation you can face lots of difficulties. It may company culture “to go and ask questions” but it can be a pain after five questions [ten maybe?]

With defensive programming, and agile methodologies around, lots of developers write their unit tests, created their exceptions carefully, every piece of code is in UML diagrams [object and sequence models,…] but unless it is a culture, nobody creates comments in their code.

Some does, but this becomes more confusing since there is no standard, a few people apply their own standards…

From the very beginning of the .NET [and C#], <summary> tags are there for documentation…This time, I will give  some examples how to use it. 

namespace  EC.Domain.ProductDMgr{ 
/// <summary>  
/// Product Data Transfer Object  
/// </summary> 
public class ProductDTO{ 

  private readonly int prodId; 
  private readonly string title;  private readonly int dissection; 
  /// <summary> 
   /// ProdId is the product Identifier 
  /// </summary> 
  public int ProdId { get { return prodId; } } 
  /// <summary>Title is the title of the product</summary> 
  public string Title { get { return title; } } 
  /// <summary> Dissection is the department of the product </summary>  
  public int Dissection { get { return dissection; } } 
  /// <summary>   
  /// The constructor of the product with identifier and title 
  /// </summary> 
  /// <param name=”prodId”>Identifier of the product</param> 
  /// <param name=”title”>Title of the product</param> 
  /// <param name=”dissection”>Dissection of the product in the store</param> 
  /// <exception cref=”ArgumentOutOfRangeException”> Exception for Dissection bigger than 999</exception>  
  public ProductDTO(int prodId, string title, int dissection) 
  this.prodId = prodId; 
  this.title = title; 
    if (dissection > 999)
        throw new ArgumentOutOfRangeException(“dissection”, “Dissection should be equal or less than 999”); 
    else
    { 
         this.dissection = dissection;
     } 
  } 
}
Anyone  using your assembly should be more confident about the objects and parameters now:

 

And during the development, that will add extra mile speed to the project:

For detailed info, you may refer to msdn.

There are codeplex projects [SandCastle, AjaxDoc] running on to extend this documentation and create msdn like help documents/websites.