How to Code Quality

Photo by Nina A.J.

Photo by Nina A.J.

Since I started out with development, the “quality” of code is always the point where reviews of code from others, boil down to. So I learned about code quality and best practices, to understand the key aspects that ensure your code is getting better over time. From standards to design patterns and the ensuring of sticking to those, is what code quality aware people nitpick about.

The key requirements to learn those practices, is to code much and always reflect on what you have done. Reflect every single bit of code and ask yourself a couple of questions like:

  • Could others understand this code a year later?
  • How long do others take to figure out what is happening here?
  • Does my function do more thing at a time?
  • Do variables and functions have names, others can understand?

Those self reflecting questions on your code quality may sound familiar if you sometimes read about code quality. This is, because code quality consists of reflection, reflection about what has been done and optimizing that. Another observation about such questions is that they should always apply on others, since code quality is all about collaboration. Today we all collaborate in company’s, on GitHub, on open source projects in general or just with some friends on a small project. This is why it is always said, that you don’t write the code for yourself, you write code for other to read. Like the author of a book, you try to craft carefully written text that is perfectly aligned to its purpose in terms of functionality and readability.

This is the meaning of Code Quality on the bigger scale. Once this settled in your mind, you only need the tools to ensure that, right? Well, since developers are their own little folk and to be distinguished by their assigned community like small little clans that fight each other, you need to pick right rules for the right thing. Luckily there are industry standards and some general rules.

Look for industry/organization standards

Using already existing standards throughout a community is best practice. Every organisation needs coding standards, to ensure their code is overall equally formatted and can be understood by most people. To iterate on those standards has benefits, since they are more likely tought out by many people and ensure that people can rely on them throughout the specific organisation. Today I would say, it is not only readability and less distraction from unfamiliar code structures that make them a must have. When developers use an IDE, they customize the settings to their coding style. We developers are a lazy folk, but in a way that we hate repeat work. So we automate things like formatting, autocomplete code and run a code sniffer. Normalizing the code layout is key, to prevent the reconfiguration of those tools and increase the reliability on those.

A very good example for this, is the TYPO3 CMS. The TYPO3 association (the organisation that runs the TYPO3 project), has their own coding standards. But the current industry standard for PHP projects is the PSR standard set, signed by many big PHP Project organisations (also the TYPO3 Association). The TYPO3 project got diverged from this standard over the time, but now the TYPO3 Association decided to refactor the TYPO3 CMS project to fit the PSR standard.

The reaction of the TYPO3 community was split, since the PSR standards requires a new line for braces in classes and functions while braces stay in the same line with logical code components like if, while, foreach and switch. Some people complained the ugliness of this coding style and the inconsistency. But compared to the whole PHP world, people are just missing what they were used to. In my opinion the PSR standard is way more tought out, than the old TYPO3 standard, since it differentiates the classes and functions from logical code components like if, while and so on. Also this formatting rule, is more consistent throughout other languages and makes it therefore even more acceptable to developers, familiar with other languages. A Coding-Standard is not about taste, it’s about collaboration!

Example of the PSR style bracing:

class MyClass
{
    public function myFunction ()
    {
        if (true) {
            return true;
        }
    }
}

And since this kind of coding standard is driven by a bigger organisation and many qualified people, you can rely on that. It is likely that these standards are already configured as preset in your IDE, and many sniffers will also have presets for them. You don’t have to care about a whole standard anymore, you can rely on great things people have done. In this case, swimming with the others will save you time and money.

Stick to design principles

This is a very good one, since I found for myself, that design principles are the bread and butter in reflecting on your own code. A design principle is more like a general rule, to avoid a code mess. They are usually provided as easy to remember acronyms and will indeed solve obstacles you run into, as your code gets more complex.

One of my favourite ones is SRP (Single Responsibility Principle). In the Linux world, this is also known as “Do one thing and do it well”, since it says your classes and functions should stick to one single job. The book “Clean Code” from Robert C. Martin, showed me how this can be applied very well in your daily coding routine. In the book, he describes how he refactor’s code. One of the first steps is isolating the responsibility of functions and even splitting functions in multiple, well named functions. A class should only contain functions, that fit in its purpose. The functions you write, should always go deeper in abstraction. Abstraction is important, since you break your function down into smaller and smaller pieces. A neat side effect of that is, you can write simple tests for them because they only do one thing and therefore have only a couple of possible results.

The SRP and other Important principles, are combines to the SOLID principle. The beauty of those principles is, that they can be followed at any time. When writing code, simply keep them in mind and check your code for them. Apply them where you can and argue with them in code reviews. I found myself improving on those rules and I even was able to fix bugs and change code faster, where I applied those rules.

Know and apply design patterns

This one is difficult, since design patterns are not only a whole science by itself, they also need to be evaluated on the situation. You can’t simply spread design patterns in your code as you please and feel good. You need to understand design patterns and learn the positive and negative aspects of each pattern. A design pattern is a tool to solve a certain problem with an elegant solution if applied correctly. They describe how for example a Singleton should be implemented, or describe a whole architecture like the MVC (Model View Controller) pattern.

Those patterns are important for designing your code architecture, since they decide in what way you will later be able to expand your Project. A good architecture and a well tought out structure is key for the maintainability of your Code. However the details about each pattern would overextend the purpose of this post.

Anyway there is another interesting approach to design patterns, by analyzing the area of antipatterns. Patterns in general, are just ways something is done over and over again. Also bad things are done over and over again and knowing the patterns of bad things make you more aware on preventing this behaviour. A good book about antipatterns in development, is the great Antipatterns book. The book kind of old, but most of the parts still apply, however it is written in a science like fashion, so its kind of dry to read.

Ensure the Code-Quality

Once you and your organization have decided on some rules, it is time to ensure everyone is following them in their full form. But that is kind of tricky to do, since you should ensure them and not enforce them. Enforcing the Rules is easy, you simply write some Git-Commit hooks that prevent pushing code, not succeeding at the codesniffer of your choice. The problem here is, you will slow down development and prevent sometimes required shortcuts. Yes, a clean code is nice to see and everyone should do that all the time, but sometimes you need to do things fast or you need to work around some unwanted behaviour of your chosen framework or language. This will make justifying your code quality actions more difficult, since you are slowing down the workflow.

Ensuring code quality should work with a mindset for the standard in every developers head. Do code reviews and talk about code, since you not only get told how others see your code (remember the collaboration thing I said), you also get feedback how to improve the code. Developers love to talk about code and we love to nitpick about code. If someone complains about a part on your code, remember why you did that and work out how you should have solved that problem. This way, everyone learns from the experience. But whatever you do, stay on topic and don’t blame each other for anything. If someone argues about code, a discussion on the topic will clear the lines. Ensure everyone is interested in good code and the code quality increases by itself.

You can also provide tools and automated tests, to check the code quality from time to time. This way you don’t prevent anything, but you can measure the overall quality and react on quality drops. Discuss what and why it happened. Most likely the problem will sort itself out by talking. Integrate code quality tools in your IDE, to always keep an eye on your quality.

 

Most of us work on collaborative projects, we need to work together in order to archive great software. In todays development cycles you don’t want to program alone without feedback, you code together. Getting better at producing high quality code is not an easy thing to do, you need to work on it and fight the bad habits all the time. But it is worth it. It improves everyone’s working speed and you gain more self esteem for the code you produced. You will have interesting discussions about details and certain performance bottlenecks. It improves not only your code quality, it improves your coding experience.

Share this Post

Florian Tatzel

I have studied computer science with weight on media and currently work as web developer at a TYPO3 agency in germany. I like OpenSource projects and contributing where I can. I also like to share knowledge and discussing hot topics in the bussiness, like Workflow trough Virtualisation and Code Quality.