Writing Quality Code

unsplash.com by NIKON CORPORATION, NIKON D610

People read and write code as well as computers interpret and execute code which are the instructions and rules, the biggest task faced with software engineers and developers is to write code that can easily be understood by humans and still interpreted by computers.

Humans by nature make mistakes (human error) but are engineered in a way that they adapt in response and unconsciously accept those mistakes, correct them and move on, these mistakes are forgotten and the content presented is remembered. On the contrary, computers (computer error) literally interpret what is told to them, if mistakes are given then the computer will dutifully execute them. For example if a computer is told to store an email of a person and an image of an animal is given, if no validations is put in place to prevent this from happening, the computer will happily store the image.

The intention of this article is to improve how software engineers communicate with computers and humans through the code they write. This article was inspired by a course taken on linkedin learning by Jon Peck about nodejs testing and code quality (link to the course) and most of the statements written here are an exact match to what was spoken in the movie if not all. Without wasting any more time let’s get to the actual business. Hope you enjoy reading the article.

What is Code Quality?

According to Joseph Juran’s Quality Handbook quality is explained with two pieces, Quality consists of those product features that meet the needs of customers and thereby provide product satisfaction. The other piece is quality consists of freedom from deficiencies.

Let’s derive the Code quality from the definitions given above;

Quality code should meet functional requirements

When we talk about functional requirements we mean the code does what it is supposed to do as an example let’s take storing an email. The requirement is to store an email address, so if the system can’t store the email address then the system (code) failed the storage requirement, if the system is able to store an image of an animal (store non-email) then the system failed email address requirement.

Quality code is deficiency-free

When we talk about deficiency-free code we mean no code failings or shortcomings. Code failing or shortcoming can boldly be generalized in two ways;

Usefulness of code

What is Useful Code?

The more flexible and reusable the code is, the more useful the code is, let’s take an example of a function that adds ‘1’ to another number and returns a result. This may fulfill the functional requirement but it is inflexible.

But the above function can further be improved by allowing any number to be added to any number. This makes it more useful because now it can be used literally anywhere in code to add any numbers together. With this it is advisable to always use the programming language built-in math library available as for this challenge at hand, that would be the more useful of all

Maintainability of code

What is maintainable code?

There are three factors to determine if code is maintainable or not.

1. Can you personally maintain the code?
2. Can someone else maintain the code without asking for help?
3. Can someone else read and understand the design and intent of the code?

If the answer to all the three questions is yes then the code is maintainable otherwise not.

One thing to note though is that maintainable code is not absolute, it evolves over the life cycle of the software.

1. Code may start as unmaintainable and improve over time and on the other hand, sloppy and inconsistent changes may make it worse over time.
2. Engineers improve with experience, so revisiting old code may make you want to improve it up.

The goal here should be continual, gradual improvement, it’s best to make a series of improvements rather than a radical whole, this way it reduces the risk of damaging functional code that was otherwise working without a problem.

Looking at this, we now know what questions to ask to determine if the code is maintainable or not. What is the most certain way to determine if code meets those standards?

a). Peer Review, where another person reads your code and documentation. If they can understand the design and intent then the code is maintainable.

You can take steps to improve the maintainability of your code;

1. With the use of consistent formatting and logical naming which helps other people to read it.
2. Using clear and appropriate comments and functional documentation that describes the intent.
3. Using appropriate modularization and atomic components makes the code reusable.

As we come to the end of this article, there is still one more question to ask ourselves. Should every piece of code you write be high quality? To answer this. We should always strive for excellence but be reasonable at the same time, sometimes one-off scripts can be necessary but still document what it is doing, why it was needed, and when it is needed. This can be achieved by a quick comment and a commit to the source code as you might need to refer to it later or even reuse some of the script functionality elsewhere.

Code quality meaning can be summarized in three main ways;

1. Code should meet functional requirements.
2. Code should be maintainable by yourself and others.
3. Code should be useful in multiple places even in different programs.

Hope you enjoyed reading the piece as I enjoyed writing it.

Reference

What is code quality? - Node.js: Testing and Code Quality Video Tutorial | LinkedIn Learning…