Documenting Your Code

This is a continuation of my previous blog

Top 10 Things Every Developer MUST Do

1. Documenting Your Code

I have seen developers do not like to write documentation. Obviously, there are tight deadlines and frequent deliverable but it does not take too much time to write about the functionality you are implementing. If you spend 1 hour for every 7 hours of code you write or even less, it will go a long way and eventually will save your company a lot more time.

OK, let's try to understand this with an example.

So here is some sample code. As you can see from this method called MessySample, I create two ArrayList objects and add some integer and string values to them and display the contents on the console.

private void MessySample()

{

    ArrayList obj = new ArrayList();

    obj.Add(32);

    obj.Add(21);

    obj.Add(45);

    obj.Add(11);

    obj.Add(89);

    ArrayList obj2 = new ArrayList();

    obj2.Add("Mahesh Chand");

    obj2.Add("Praveen Kumar");

    obj2.Add("Raj Kumar");

    obj2.Add("Dinesh Beniwal");

 

    int bs = obj2.BinarySearch("Raj Kumar");

    Console.WriteLine(bs);

 

    foreach (object o in obj2)

    {

        Console.WriteLine(o);

    }

}


Nothing wrong with this code. Right? WRONG!  

Problem with this code is, if I end up using these ArrayList objects somewhere else or some other programmers read this code, they have no clue what obj and obj2 are, unless the go through the code line by line. I also do not know what this method really does and where can it be used.

 

OK let's spend 2 minutes on this above sample code and apply some comments as shown in the sample code below. As you can see from this sample code, now if anybody reads this code, they will exactly know what this code will do. Only thing you did is, just added some comments to the code.

 

/// <summary>

/// This is a MessySample method that shows how we can write messy code

/// </summary>

private void MessySample()

{

    // Create an ArrayList object to store integer items

    ArrayList obj = new ArrayList();

    obj.Add(32);

    obj.Add(21);

    obj.Add(45);

    obj.Add(11);

    obj.Add(89);

 

    // Create an ArrayList object to store string items

    ArrayList obj2 = new ArrayList();

    obj2.Add("Mahesh Chand");

    obj2.Add("Praveen Kumar");

    obj2.Add("Raj Kumar");

    obj2.Add("Dinesh Beniwal");

 

    // Apply binary search

    int bs = obj2.BinarySearch("Raj Kumar");

    // Display index on the console

    Console.WriteLine(bs);

 

    // Send ArrayList items to the console

    foreach (object o in obj2)

    {

        Console.WriteLine(o);

    }

}

 

 

Coming next

2. Keep Your Code Clean