Comments in C#

• Use paragraph comments
  
  If you comment is very long in line of text break into paragraph show it can be seen in a single view.
  
  Instead of writing like this:

  // Author Puran Singh Mehra. Xyz Company. Created on 7th December 2008 12:23:34 P.M.  

  Break into different lines like this:

  // Author Puran Singh Mehra.   
  // Xyz Company.   
  // Created on 7th December 2008 12:23:34 P.M.   

• Consistent style of commenting
  
  Some people believe that comments should be written so that non-programmers can understand them. Others believe that comments should be directed at developers only.
  
  Comments are consistent and always targeted to the same audience. Comments should target to developers and non-developers.

• Don't insult the reader's intelligence
  
  Avoid obvious comments such as:

  int age = 45;  
  if (age >= 18)  // If age is greater than 18 a person can vote  
      Console.WriteLine("Vote");  
  else  
      Console.WriteLine("Can't Vote");

  This wastes your time writing needless comments and distracts the reader with details that can be easily removed from the code.
• Comment code while writing it
  
  Add comments while you write code and it's fresh in your memory. If you leave comments until the end, it will take you twice as long, if you do it at all. "I have no time to comment," "I'm in a hurry," and "The project is delayed" are all simply excuses to avoid documenting your code. Some developers believe you should write comments before code as a way to plan out your ultimate solution.
  
  For example:

  protected void Button1_Click(object sender, EventArgs e)  
  {  
      // On click of button check prior that values are entered properly in order  
      // Validate date for range and data types  
      // ask before submitting values  
      // make this entry in the database  
      // then you can follow your code  
  }

• Write comments as if they were for you (in fact, they are)
  
  When it comes to commenting code, think not only about the developers who will maintain your code in the future, but also think about yourself. In the words of the great Phil Haack:
  
  "As soon as a line of code is laid on the screen, you're in maintenance mode on that piece of code."
  
  As a result, we ourselves will be the first beneficiaries (or victims) of our good (or bad) comments.
• Write a comment in a polite manner
  
  Avoid rude and harsh comments. You never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted. So maintain your respect and dignity.
• The golden rule.
  
  Let the code speak for itself. You code should be written in such a way that everyone should easily understand it.
  
  For example:

  public Form1()  
  {  
      InitializeComponent();  
      SqlConnection con = new SqlConnection("Data Source=MCN002;Initial Catalog=puran; Integrated Security=True");  
      string cmd = "Select * from testpuran";  
      con.Open();  
      SqlDataAdapter da = new SqlDataAdapter(cmd, con);  
      DataSet ds = new DataSet();  
      da.Fill(ds);  
      dataGrid1.DataSource = ds;  
  }

Conclusion

Hope the article would have helped you in understanding comments and their usage and importance in coding. Proper usage of comments makes your code easily to understand and improve performance.

Your feedback and constructive contributions are welcome. Please feel free to contact me for feedback or comments you may have about this article.