Why Code Readability is important

If you struggle to read the code, how the hell are you meant to fix it – Hosk

Code readability is one of the most important qualities of good code, like the art of writing code it’s a subjective topic which varies between developers.

If code is easy to read, it will be easy to understand which makes it easy to debug, maintain and extend.  Writing readable code is easier said than done, making complicated code easy to read and understand is a very difficult skill.

Learning to make code readable/understandable is difficult for inexperienced developers to not only do but understand because it can be difficult to quantify the differences between readable code and un-readable code.

It often easy to spot good code and even (often) easier to spot bad code but when asked to explain why some code is good and other code is bad a lot of developers will shrug there shoulders and just say “Because it is”.  Similar to when you know something isn’t right, it doesn’t feel right but you are not sure why.

Why is code readability important?

When a developer initially writes the code their knowledge of the system is very detailed because usually they have worked on the project for some time, read requirement/technical specs.  They know the code/related code, they know the system, everything is in harmony.

6 months or a year later no one is going to know the system that well again, so you have to understand how the code works by reading it.

Poorly written code can make this very difficult, code with poor readability is

• Difficult to understand
• Longer to debug
• hard to maintain
• tricky to extend

Code Readability in Dynamics CRM

I have seen a lot of CRM plugin code, I have come to realise when you see some good code you are excited because there is a lot of plugin code which is smelly (code smells)

Some of the reasons/excuses is because CRM plugins can be written quickly, a lot of CRM developers do write them quickly and create one big method in the plugin which does everything.  This creates plugins which 100’s  of lines long, do retrieves, calculations, make a cup of tea.  These plugins are hide to read, difficult to debug and a nightmare to change/extend.

If you don’t or didn’t do code reviews, code which works can be added and the unreadable code lurks in the system until a bug appears.

The classic scenario will usually involve the writer of the code no longer working at the company, someone else having to find and fix the bug.  This is when you will be confronted by code which is not only difficult to read but damn right confusing, making fixing the bug 10 times harder and 10 times longer.

There is rarely time made to go back to refactor projects so the best way to avoid this problem is to get it right first time and create readable code.

So what makes code readable?

Comments

So people might think the way to make your code readable is put loads of comments in it.  Some well placed comments will certainly help when you get to a tricky bit but most code should be self commenting by using well named variables, functions, classes etc.

More comments does not equal better readability and in some cases extra comments can just clutter up the code.

Well structured code/Good Design

Well structured code is split up into logical/well named classes and methods.  The structure of the code is linked to the design, classes and methods should have a clear separation of responsibility (and decoupled)

When thinking about the structure of your code remember this line

Code should have a clear purpose

The line above means is all the classes and methods should have a clear and easily understood purpose and if you are having trouble naming classes and methods it’s probably because they are doing lots of different things.

Consistency 

Code in all the plugins and Javascript should be consistent, even when different developers have written it.  I find it frustrating when you work on a CRM project and the code can change in style, shape, naming conventions and structure.

The structure of the code should be the same between plugins, so when you are debugging and reading those plugins you can instinctively look in the same areas each time.

These should be consistent

• Code Formatting
• Braces
• naming (classes, methods and variables)
• folder structure

Small is beautiful

Methods and classes should not be to long, if they are the code is doing too much.  Methods should do one thing and decoupled (which will allow for reuse)

No Magic numbers

Instead of assigning a field the value 2, create a constant which explains what the value 2 is.  This will not only help others understand the code but in 6 months time you will find it will help yourself understand what 2 is.

No One line wonders

Some developers believe the smaller number of lines written the better the code.  This isn’t the case if some of your lines keep going and going and going and going, so the developer has to scroll across to read it.  Split the code into a few lines and make it easier for people to read and understand.

Get rid of duplicate code

If code is being duplicated or very similar code is created, then create a modular function and use it.  This makes it easy to read because its only one class/function and you will soon learn what it’s doing. It’s also less code to read.

Duplicated code is a sign of lazy programmers who can’t be bothered to create reusable code, this should be a warning sign that poor code is being written and standards are dropping.

Why am I talking about Readability

I had a bug today and 3 developers (one of them me) had no idea what or how the code was working.  We have a grid in CRM, which is a fantastic looking grid, it has icons in and to the user it’s magnificant.  It’s referred to as the magic grid.  It’s called the magic grid because it’s magic (as in good) and because no one really knows how it works apart from the developer who created who has now left.

People try to avoid making changes to the magic grid because the code is complex and does not score high on the readability scale.

The magic grid was automatically selecting some items, why?

I finally tracked down one part which was making the items in the grid automatically selectable, it was changing month13 to either the value 2 or 3.

       //Deal with present
        //Overdue
        if (nextService != null) {
            if (nextServiceYear < visitDateYear || overDue) {
                var month = "month13";
                gridItems[index][month] = "3";
            }
            if ((nextServiceYear === visitDateYear && nextServiceMonth < visitDateMonth) || overDue) {
                var month = "month13";
                gridItems[index][month] = "3";
            }
                //Due Today
            else if (nextServiceMonth === visitDateMonth && nextServiceYear === visitDateYear && !overDue) {
                 var month = "month13";
                gridItems[index][month] = "2";
            }
        }
        else {
            var month = "month13";
            gridItems[index][month] = "0";
        }

Then later when drawing the grid

else if ((item.month13 == "2" || item.month13 == "3" ) && item.manuallyAdapted != true) {
//Next, reevaluate the grid selected values so overdue/due now items are selected
 item. select = "true";

 

Then later when drawing the grid

else if ((item.month13 == "2" || item.month13 == "3" ) && item.manuallyAdapted != true) {

//Next, reevaluate the grid selected values so overdue/due now items are selected

item. select = "true";

Month13 was a weird extra month, which was being used to hold values used in the functionality but no where was the number 2, 3, 0, 4 explained as to what they meant.  It literally was magic!

Something extra smelly for you

If you want something else interesting in this error, try Code Smells

Advertisement