Good code is self-documenting

Picking a good name for a class/method is often very difficult. But if the names are chosen carefully the code often needs no further documentation.

For instance compare these two simple examples (they are functionally equivalent):

   1: /// <summary>

   2: /// Summary for Bounds class

   3: /// </summary>

   4: public class Bounds

   5: {

   6:   public int m_A;    // lower bound

   7:   public int m_B;    // upper bound

   8:  

   9:   /// <summary>

  10:   /// Creates a new Class1 instance

  11:   /// </summary>

  12:   /// <param name="a">the lower bound</param>

  13:   /// <param name="b">the upper bound</param>

  14:   public Bounds(int a, int b)

  15:   {

  16:     // m_A should be the smallest value

  17:     m_A = Math.Min(a, b);

  18:     // m_B should be the biggest value

  19:     m_B = Math.Max(a, b);

  20:   }

  21:   …

  22: }

   1: public class Bounds

   2: {

   3:   public int m_LowerBound;

   4:   public int m_UpperBound;

   5:  

   6:   /// <remarks>It is OK to provide a & b in the wrong order.</remarks>

   7:   public Bounds(int a, int b)

   8:   {

   9:     // The rest of this class assumes that m_Lowerbound <= m_Upperbound,

  10:     // so we fix it here

  11:     m_LowerBound = Math.Min(lowerBound, upperBound);

  12:     m_UpperBound = Math.Max(lowerBound, upperBound);

  13:   }

  14:   …

  15: }

Although the second example has less comments, I feel that it is better documented because it is self-describing:

• The default class-comment that is inserted by Visual Studio is useless. The name of the class is already sufficient documentation.
• The second example has good names for the fields; further comments are not necessary.
• The first example has comments about stuff that is very obvious (every developer should already know what a constructor does).
• The first example explains the sorting of the parameters but every developer can see what is going on. The second example instead explains why the parameters need to be sorted.

If your code is written cleanly then you don’t have to document what it is doing. But you may have to document why it is doing it.