Wednesday, August 27, 2008

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.

5 comments:

Donny said...

I totally agree with you on this. I try to do this in my own code. I often run across code from other developers that have these cryptic 3 to 5 letter object and property names. Very annoying.

Tiemoon said...

Thank you, Kristof. It's really sad that most of developers use cryptic name for classes and for their attributes and methods also. So, the clients (who will use these classes) face unnecessary obstacle and it kills their productive hours. Thank you again.

Tiemoon said...

Thank you Kristof. It's really sad that most of developers use cryptic name for class, for it's attributes and for methods. So, the clients (who will use the class) face unnecessary obstacle and it kills their productive hours. Thank you again.

Tiemoon said...

It's really sad that most of developers use cryptic name for class, for it's attributes and for methods. So, the clients (who will use the class) face unnecessary obstacle and it kills their productive hours.

Jon said...

Your second example has a small error. The parameters to the constructor are a and b, but later in the constructor they are called lowerBound and upperBound. It's pretty obvious what you meant, but probably worth correcting.