Simple Tips To Help You Write Friendlier Code

Clean Code.

To paraphrase BJarne Stroustrop, Clean Code is elegant, simple and efficient and does one thing well. I particularly love this statement because it has always been a strong belief of mine. I will now attempt to go through a few simple every day checklist that can improve code readability and ultimately, maintainability.  

Tip #1: Identifiers

Identifiers, functions, classes/interface, should have names that are clear and concise. Most developers, including myself, love to write code late at night. This is when we can crank out our latest and greatest. But if you are like me, when you look at that same piece of art you cranked out a few weeks ago (or even the night before), you can hardly recognize what the variable call killSwitchForCat means. 

Below is a table of good and bad identifiers just to give an idea.

Bad Good
int w = dayOfMonth/7; // what is ‘w’ in the equation int week = dayOfMonth/7;  //Write what was intended
int l; // don’t know if this is 1 or lowercase L int length; // This is more easily identified and is even more searchable in Visual Studio
   

 

Tip #2: Naming Methods

Methods are some of the hardest things to name at times… especially when you have no clue what it really does. This tip is similar to tip #1 but is accompanied by an additional condition. Methods should be named according to the task they perform. This leads me to OOD (Object Oriented Design) 101 which says that your methods names should be the verb phrases from your design. 

E.g. 

GetProducts()
SaveProduct()

Tip #3 Consistency in Method Operations

Have you ever inherited code where you have 2 or more methods with the same (Overloaded) and you think to yourself, “They have the same name and since I know that this one does task A then this other method with the same name must perform the same task A.” Then you build and run only to find you crash with an exception only an alien can decipher. 

E.g.

 

void SaveProduct() 

    { 

        EnsureConnection(); 

        SaveToDatabase(CurrentSelectedProduct); 

    } 

    void SaveProduct(Product product) 

    { 

        //You may get a crash here because ProductRepository.Products may be null 

        Merge(ProductRepository.Products, product); 

    }

This one will save you a lot of time and trouble in maintenance and readability. 

Tip #4 Rule of Three: Function Are More Readable When Segmented

This one I learned in my first year of college yet have time and time again neglected this simple rule.
When you write a function you should divide it into 3 segments.
i. Declarations
ii. Initializations
iii. Functionality 

E.g.

double ComputeLogOfBaseN(int baseN, double number) 

    { 

        int result; // Declaration 

        result = 0; // Initialization: I know this is unrealistic but I am simply making a point; 

        result = log10(number) / log10(baseN); // Functionality; 

        return result; 

    }

 

Tip #5: Function Arguments are more readable when <= 3

Have you notice that in the .Net framework most methods that you have to deal with on the regular have 3 or less arguments. The more arguments a function has the harder it is to read. Readability is the key to maintaining code. If you have a function that takes more than 3 arguments I suggest encapsulating them in a structure that is light weight. 

Tip #6: Functions should have one entry and one exit.

Consider this function:

bool EvaluateUser(User u) 

{ 

   if(!u.IsActive) return false; 

   else if(u.IsOnline && !Role.IsInRole(“Administrator”, u)) return false; 

    return false; 

}
//VS

bool HasAdminPriviliges(User u) 

{ 

   bool canProceed = false; 

   if(!u.IsActive) canProceed  = false; 

   else if(u.IsOnline && Role.IsInRole(“Administrator”, u)) canProceed = true; 

    return canProceed; 

}

Note: One return statement

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s