Write it like you would write a book – clean code

More often than not we come across code that has received little syntactic sugar from its author. In this post I will outline a few simple tactics and tools to improve the readability of your code in just a few simple steps! In this article I will focus only on the syntactic markup of code.

I acknowledge that good code requires the use of proper OOP concepts and applying correct programming patterns. As we are well aware, a lot of projects lack time, money or resources to apply these concepts so my focus here is on the syntactic markup of code only.

Personally I like to compare the writing of readable code to the writing of a book. For example, take the text from this blog’s landing page; the ‘about Tomas Schulkes’ page. Now imagine you would have had to read that text formatted like this:

I

 

enjoy solving

problems and                           finding solutions by turning CRM                        insights into new designs. Keeping

up to date with the latest improvements in Dynamics                                  CRM,                          I          am not one to pass up on a challenge. I have been enjoying Sydney and it’s surroundings

since 2014, when I moved to Australia.

I                                                             star-

ted my career at Avanade Netherlands where I was introduced to CRM 4.0.

 

I ….

(For reference, at the time of writing this post, the text on that page starts as follows:)

I enjoy solving problems and finding solutions by turning CRM insights into new designs. Keeping up to date with the latest improvements in Dynamics CRM, I am not one to pass up on a challenge. I have been enjoying Sydney and it’s surroundings since 2014, when I moved to Australia.

I started my career at Avanade Netherlands where I was introduced to CRM 4.0. I ….

Which do you prefer? If your answer is the former text, then please scroll back to the start of this article and try again. If your answer is the reference text, then I ask of you: why would you not want to apply proper formatting to programming code?

No one in their right mind would expect their audience to read their entire text if it were formatted like it is in the first example. And, if they did make the effort, it would take the reader a considerable amount of extra time to comprehend the author’s message than it would if it had been formatted properly.

Code is no different!

Yes, to the modern compiler the ‘text’ would be no different whatever the markup of your code. But as a developer your audience is far broader than just the compiler: think your colleagues, external code reviewers or readers of your blog, just to name a few! Let us help each other and change the way code is written forever.

Some simple guidelines can improve your code incredibly:

  • Control+K+D  (Visual Studio Auto Format short key) is your first step towards working wonders! Pressing this key combination indents all lines based on the depth of their scope, removes unnecessary white space within a line and puts curly braces on their own lines.
  • Next up, make sure there is no unnecessary white space. What is the benefit of having multiple lines of white space over just 1 line of white space? Why have one or more lines of white space between two scope close signs (closing curly braces)? Just like formatting in a book, having consistency in the spacing of your code adds to the readability.
  • Ever tried to right click on your c# source file, opened the ‘organize usings’ menu, and then clicked ‘Remove and sort’? Do it now and satisfy your OCD forever. (Note: usually your code must compile without errors for this function to be effective)
  • Then another thing: documentation. Properly documented code reads quicker than a bare code class. The definition of proper could be open to interpretation, but generally you will want to capture a summary of what the documented part of your code does. No need to write a book; a caller generally will want to consider a function a black box. Just capture the essentials: input, output, and how input maps to output. GhostDoc (click here to visit page) to the rescue! If you haven’t downloaded it yet, do so now. Using a simple short key, GhostDoc will generate a comment template for your function or class, and even prepopulates some comments based on function and parameter names.
    Visual Studio (2015? and above) can display your JSDoc comments beautifully while programming in JavaScript. Please see this link:
    Create JSDoc Comments for JavaScript IntelliSense
  • Want your entire team to write all of the code in the same style and using the same rules? Download, install and use StyleCop (click to go to page). This tool analyses your source code on demand and has a consistent set of configurable rules that will make every individual developer in your team write the same style of code. For example, it will tell you to group methods, properties and other class code in a consistent order and grouped by access modifier.

These are just a few methods and tools of writing consistent code. You can throw your own in the mix, or use a completely different set of tools and markup rules to achieve consistency. Whatever you choose, stick with it and make it read like a book!