Code quality can translate into how useful and maintainable your code is: high-quality code can be re-used and re-developed; low-quality code doesn’t last.

Projects are often a race against the clock and the budget so tight that counting on a couple more hands to write code is a chimera. Cutting corners may seem the easy way out, but it will not pay in the long run.

Well-structured code, following language rules, is much easier to read and understand by different browsers and other developers. It is also more reliable and avoids future rework.

So, what is code quality after all?

Software projects can be subject to different constraints at different stages (from requirements to analysis, development, testing, deployment, and maintenance) which can sometimes lead to the code itself being handled as the least important aspect (function over form). However, one of the most important – and often forgotten – properties of good software is its code quality.

Code quality can be measured in a number of different ways, but some of the most important aspects are:

  • Readability, consistency – how easy it is to read and understand sections of the code; this includes code clarity, simplicity, and documentation.
  • Predictability, reliability, and robustness – software behavior should be predictable, and not prone to hidden bugs.
  • Maintainability and extensibility – fixing, updating and improving software should be as simple as possible, not inherently complex.

Why does code quality really matter?

Given the usual constraints already present in software development, why should the effort to produce quality code be so important?

Writing quality code should not be regarded as a time-consuming task, but rather as one of the main goals when developing software; it should be considered as an essential investment on which return will follow almost immediately:

  • Code that is highly readable, consistent and documented is easier to review, leading to a much lower development effort.
  • Clean and elegant code is also much easier to understand, maintain and extend.
  • Software that is well designed and achieves a lower code complexity also benefits a great deal in terms of testability and robustness (less prone to new bugs being introduced).

In essence, a high code quality is one of the most effective ways of lowering technical debt.

Let me show you an example

Poor quality code can be usually caused by:

  • Lack of (or insufficient) coding style/standards.
  • No / poor documentation.
  • Poorly designed architecture (with no separation of responsibilities, as in MVC).
  • High method complexity

In the following example, the purpose of the method cannot be clearly identified without careful examination:

  • There is no function documentation, no comment lines, and no apparent coding standard is followed (seen, for example, in the usage of curly brackets and empty lines).
  • The complexity is relatively high due to the number of different actions and processes (DB queries, view/output, and business logic), multiple nesting levels.
  • There is an inconsistency in the ways to perform output and variable interpolation.

Given its low quality, the code is prone to errors/bugs (not to mention security concerns), and difficult to test properly.

In addition, any changes to the software will probably result in an increased development and testing effort and still result in potential new bugs being introduced.

On the opposite side, following a coding standard and documenting code is a key aspect of the quality.

A random example of this can be seen in the following picture, a section of Symfony’s FrameworkBundle Controller.php:

Besides the method/parameter documentation, we can clearly see that:

  • The code is simple and self-explanatory.
  • Different logic sections are separated by empty lines.
  • There are few nesting/indentation levels, with early return statements.
  • There are proper design considerations (separation of responsibilities by different objects/classes).
  • Due to the high code quality and clarity, the class/method should be easy to test and maintain, with low effort; the probability of bugs occurring should also be extremely low.

How can a high code quality be achieved?

Here are a few tips:

  • Choosing an appropriate coding (style) standard for the language or framework. For PHP, for example, PSR-2 can be considered as the current standard recommendation. It may be possible to integrate CS fixer tools with your development environment (see php-cs-fixer)
  • Consistency in class, method and variable names is another important factor of readability.
  • Making sure to properly document classes, properties, methods, and particular blocks of code when necessary, assuring comments are simple, concise and effective.
  • Refactoring and choosing correct design patterns is a good way to promote code reusability and extensibility, and to achieve a lower class/method complexity.
  • Adding code analysis tools to the CI environment, to be executed before merging new changes. For PHP, phpmd and/or phpstan are tools that can warn of potential problems in the code and have a number of different configurable rules.
  • Automated testing is another must-have; not only will it help to prevent new bugs, but also to ensure it meets requirements and responds correctly to different inputs.
  • Finally, leveraging tools such as scrutinizer-ci and Codacy to test and display a clear overview of the quality of a project over time, and important details about what and where the issues are.

Bottom line

Regardless of development methodologies, languages, frameworks or tools, enforcing a high code quality is a way to achieve faster and easier development, testing and maintenance, which results in reduced costs of software ownership.

 

Written by João Inácio | Senior Developer and Team Leader at Cleverti