How to write explicit code? — Onload Code
By: Maduka Jayawardana
Tags: Good Code, Clean Code, Explicit Code

In this article, we are talking about the concepts and examples about the topic of how to write explicit code

How to write explicit code?

You want to know what is explicit code to become an explicit programmer, don’t you? That is why you are reading this article. Unfortunately, you can not find the exact definition for your question anywhere because it is difficult for us to say for sure that explicit code is like this. In simple words, we can say this:

“Clear code is code that is easy to understand, easy to change, and performs fast.”

OK. Let’s go deep down into this statement.

You are not the only one who reads the code you write. Your colleagues, your tech lead, your project manager, or a developer who will handle the project after you may read your code many times. So when you or they read the code, it should be easy to read and understand. That means if someone takes less time to read and understand its logic and functionality, then it will be an easy-to-understand code. Moreover, an easy-to-understand code is less prone to guesswork and misunderstandings. Explicit code is easy to understand in all aspects.

It is easy to understand:

The flow of execution of the whole program

The way various objects cooperate with each other

The role and responsibility of each and every class.

What each function or method does

The purpose of each variable and expression

1. Well-named classes, methods, and variables comply with proper naming conventions and meaningfulness.

boolean variables’ names with is_, has_, or should_ prefix, e.g., $is_valid=FALSE;

Numeric variables with names that denote it is a numeric variable, e.g., $total_comments=50;

List variable names with plural names for connoting many items, e.g., $new_names=array(….);

Method names that describe its functionality, e.g.,format_comments()

2. Comments for describing the purpose of each variable, method, and class

3. Properly structured code with proper indentation

4. Compliance with coding standards and conventions

5. Consistency in coding style

For example,

a. the way you are placing braces in the code

b. consistent naming

6. Well encapsulated code

Wrapping variables and methods together as one unit.

7. Well organized code

Data and functionalities in a class fit together. You can not find extraneous dependencies among classes. So well-organized code does not seem like “spaghetti”.

8. Separation of concerns

In simple words, a code is divided into multiple chunks that are designed to perform one specific function.

9. Simplicity:

In simple words, not writing ten lines of code for something that can be done in 5 lines of code.

10. Straightforwardness

Straightforwardly doing a task without being clever

11. Modularity:

The entire source code is divided into multiple independent functional reusable units.

12. Elegance

In other words, less complexity in the code. If your code is given to another developer to work on and he or she can continue the work without much effort, then your code will most probably be an elegant one.

13. Minimum redundancy

This means a code with fewer unnecessary codes like dead codes.

14. Layers that do not mix with each other

For example, UI does not mix with business logic.

15. Properly structured README file

Briefly describing the overview of the code, its purpose, the approach, metrics involved, naming conventions, libraries, and packages that are used in the code, software license, software version, and author details.

As stated above, another attribute of explicit code is that it can be easily changed. This means your code should be easy to extend, easy to refactor, and easy to fix bugs. If the developer who makes the changes, can thoroughly understand the code and he or she is confident that the changes will not break the functionality of the rest of the code, then this can be easily achieved. An easy-to-change code has the following properties:

● Always use small classes and methods.

● Each class and method complies with the Single Responsibility Principle (SRP).

● Classes with concise public APIs.

● Classes and methods work properly as expected.

● Easily testable code

● Easy-to-understand and easy-to-change test cases

The last attribute of explicit code is its fast (efficient) performance. That means explicit code does not do useless costly operations. For example, a code that executes costly operations several times or triggers N+1 database queries is not a clear one.

If you write explicit code, then you are helping your colleagues and even your future self. You are making it easier for a new developer to learn your code. You are making it faster and easier for anyone to find anything that they are looking for in your code. You are minimizing the maintenance cost of your code. You are making time estimation for the new feature implementation easier. You are reducing the time that will take to find and fix bugs, implement new features, and review. You are improving the performance of the program. You are reducing the error rate. You are making working on your code less stressful and more fun for years to come. Basically, you are making life less stressful and easier for all the people involved in the project and increasing productivity.

Conclusion

We hope that this guide helped you to get an idea about what is explicit code. So what is explicit code? In simple words, if your colleagues understand your code easily and quickly, change the code in less time without breaking down the software functionality, and are happy and relaxed working on your code, then you are writing explicit code.

If you know any other tips on explicit code or any problems related to clear code, then feel free to mention them in the comment section. And also, do not forget to share this article with others to share the knowledge. Let’s end the discussion with a quote.

“Any fool can write code that a computer can understand. Clear programmers write code that humans can understand.” — Martin Fowler