Write readable code

Introduction

Writing code which is easy to read, reduce guess work and reveals its true purpose that is not something which is easily achievable. As developer, we always endeavor to write code which will become communication tool for our co-worker.

Once I came across below code snippet in one of project (desktop application). I started thinking about API behind the method (Sleep) and code readability.

Directs way like this:

Thread.Sleep(3000);

another way (overloaded) like this:

Thread.Sleep(TimeSpan.FromMilliseconds(3000));

Well, what’s the point (in first code) writing code in a such way where we are able write the same code (second example).

Though both code snippet produces the same result but first one have a magic number (3000) means a numeric value that is encountered in the source but has no obvious meaning or we can say that code has code smell. At the first glance, if my peer reads the first code, first he tries to guess meaning of that magic number and if unable, then try move cursor over this method and read description about it whether specify numeric value is in second or minute or millisecond.

Here I have taken very simple example but try to think same thing if you are working in enterprise level application and imagine for a second if there is no code comment there.

In contrast to that, in second code example any developer can easily understand it without further thinking and guessing that current thread Suspends for the 3 milliseconds. This one improve code readability. So, there is no any chances for any developers to put extra efforts to find its true purpose which one is require in first one. It clearly reveals its intense means its dependency on TimeSpan struct and we all know that this struct contains methods and members which represents time interval.

In first example, we can refactor the code to improve readability. So, replace that magic number with constant means with an equivalent variable.  This way also we can also make code more readable for those who are unfamiliar with it. Remember one thing it would not be improve code readability if you just replace the “magic number” with variable names like A, B or X. So, try to choose variable names which explain their purpose concisely. But second one is still better because it is already available in-built in framework.

Look consider others below code snippet (Unreadable vs Readable)

1) ASP.Net

Response.Redirect("ManagePriority.aspx", false);

Response.Redirect("ManagePriority.aspx", ResponseEndEnum.EndResponse);

public class HomeController : Controller
   {
      private readonly ILogger _logger;

public HomeController()
       {
            _logger = new Log4Net();  
          }     
    }

public class HomeController : Controller
   {
       private readonly ILogger _logger;


public HomeController(ILogger logger)
       {
            _logger = new Log4Net();  
       }     
    
}

Conclusion

As you can see it’s all about code readability or we can say in another way -

Saving the time of other developer who work with you or who may update your code later. Always try to write code in expressive style and take every opportunity to self-document code through descriptive variable, class and method names.

Reference