Code that is easy to read and understand

Too often I find that I am reading code that is far too complicated, buggy or just simply ‘too smart’ for me.

A large portion of my time is spent just trying to follow deeply nested logic. It doesn’t have to be this hard. We can write simpler code if we just take the time.

By following these basic rules, we can write code that is easier to read, understand and maintain.

These are my coding ‘rules of thumb’

These are the basic rules which should apply to the vast majority of our code. As with any ‘rules of thumb’, these are guidelines and not strict rules.

When we do bend the rules, we should have a good defensible reason for doing so.

Without further ado…

Our classes should be:

• Well named
• Less than 150 lines of code
• No more than 6 dependencies
• Have one ‘main’ method or function

It should be ‘well named’

When we name something well it’s purpose and role is clear to the reader. When we code we have the reader in mind as our audience.

They should be able to easily understand what is happening in the code they are reading and this all starts with naming things well.

Names matter.

Avoid generic ‘Service’ class names

EntityService classes are an example of a badly named class.

i.e. MembershipService.cs, CustomerService.cs, AccountService.cs

We see this types of classes in our projects all of the time. They start out innocently and possibly meet the original rules of thumb.
But due to the generic nature of the class name - they tend to attract more and more methods overtime.

Eventually they bloat to 100’s of lines of code and the unit tests are no longer being maintained.

‘Service’ classes are not alone - they have equally badly named friends in

• ‘Manager’
• ‘Handler’
• ‘Repository’

Lets try and avoid these generic class names!

The next time you are tempted to name something CustomerService.cs. Stop and think a bit deeper. What is the main purpose of the class? Is it doing a particular operation on the Blah entity? If so, this should be reflected in the name.

+ public class CustomerCreator 
- public class CustomerService 
{
    public void Create(Customer entity) 
    {
        ... 
    }
}

Lets rename this class to CustomerCreator or something similar. Having a specific name will remove the temptation for class bloat.

It should be less than 150 lines of code

When code exceeds 150 lines of code it stops being easily read. We should have compassion for the reader of our code. By keeping the number of lines of code shorter we relieve the reader of the cognitive burden of trying to understand lots of complexity all at once.

By keeping the number of lines of code short we constrain the amount we are able to do and therefore do less.

It should have less than 6 dependencies

Where possible, we should restrict the number of dependencies our classes consume. The more dependencies our class consumes the harder it is to test. It is also a ‘code smell’ which indicates that our class does not have a clear purpose and possibly requires refactoring into a better state (Single Responsibility).

There are some exceptions to this rule. Some classes act as an orchestrator where they are not really performing much in the way of logic, but are responsible for processing an array of dependencies etc.

It should have one main method

Holding to the ideal of the ‘Single Responsibility’, we should only have one main method that we are exposing to the rest of the code base. This main method should be written with readability in mind.

Where possible:

• Do early exits for validation and edge-case reasons.
• Push complicated logic to well-named private methods or separate classes (Single Responsibility)
• Avoid deeply nested structures

These are my rules

These rules have helped me keep my code to a good standard. It has helped when explaining to my fellow developers what I expect during code reviews.

I hope they help you.