Be less rude — Code quality is a matter of courtesy
This is the story of my good old friend, let’s call him John. He is software developer with body and soul. And he’s smart, of course he is! John is able to solve almost all the tasks assigned to him. But John also has a dark side… cleanliness is not his key strength. And I’m neither talking about he wouldn’t follow the company’s clean desk policy nor about his personal hygiene. Not at all! He is pretty messy about his work. Unfortunately! Because…
Not infrequently, unclean work leads to long-term errors. As always when talking about software, the biggest part lies beneath the water surface. No matter if it is complexity, the LOC (lines of code) itself or even the riskiest parts of its business logic. It’s hard to imagine what mistakes are hidden inside the innumerable classes and methods of a software.
Sure, plenty of tools solely exist to protect you from bad surprises. They are literally the Holy Grail! Just put as many tools as you can find together, run them simultaneously, one after another or in any kind of weird order. This will solve absolutely all your problems! You will never ever have to think about bugs, code quality and maintainability again. Irony!
Honestly, some tools are pretty helpful. And beside them, there are even some other things one can do to improve the quality of a software. Let me show you a few tools and aspects below:
Static code analysis tools for example, like PHPStan for (who would have thought) PHP language try to detect errors right before ever running your code. A little like a compiler does when letting compile your software into byte code or an executable. Analyzing the NPath (cyclomatic complexity) of methods, existence of dependencies the code accesses (classes, methods, variables, …), finding vulnerabilities… Hundreds of rules can be configured. And if that’s not enough, just write your custom rule to verify your code base. You see, it’s not that stupid having analyzers work. They are extremely useful and supportive but also highly dependent on a correct configuration.
PHPStan focuses on finding errors in your code without actually running it. It catches whole classes of bugs even…
The PHP CodeSniffer for example is a script (or rather two scripts) which run over your PHP, JS and even CSS files just to check if they will all fit the requirements of the defined coding standards and automatically corrects occurring violations for you. Analyzing against defined coding standards — great! But auto correction? Well… I guess you have to decide that yourself!
There are also numerous Continuous Integration tools like Travis CI which further provide various features to continuously verify aspects like performance, technical debt, code style, compatibility to specific language versions, successfully running automated tests and many many more. Some of them are free to use, others (SaaS) offer different plans, ranging from a single user license to packages for teams with an unlimited amount of users. Such tools often provide the ability to deliver/deploy your code as well. That’s why they are usually known as CI/CD tools.
Travis CI is a hosted continuous integration and deployment system. You can now test and deploy open source and private…
I could list way more tools… PHP Unit to not only run unit tests but also show the code coverage of your software and the CRAP metric (displays what might be the code difficult to change). PhpLoc gives you a hint of your projects size. Another useful one, PHPCPD, scans your code base to identify if there are any duplicated code parts. PHPMND helps you to detect magic numbers in your code. As I already wrote before, I could list way more. Not only in PHP context. But enough of it for the moment.
Last but not least… even your IDE gets shipped with some integrated tools to analyze your code, to start your test suite, to run the code style linter or something else — just by simply clicking a button. Of course, this works pretty well after some configuration work. So to say “out of the box”!
Analysis tools are of course a good help to keep your project’s healthiness. Especially if they are being used in daily business. As we’ve seen so far, they will support you if you are using them wise. But that’s all you may expect. Code quality can not be created by all the tools and scripts in the world. So please stop thinking that code quality is just another metrical value, something to be excited about.
Code quality is a matter of courtesy!
But what is “code quality”? These two promising words just combine all you will be able to do to improve the following key aspects:
Code quality is thus the foundation of the success of solid, maintainable and well constructed software. Rather, code quality is the cornerstone of successful team collaboration as well as the link between economy and predictability of any software project. And code quality affects different parts of a project environment. Let’s take a closer look at what code quality means…
Totally understandable… first of all, most of the code quality improvement measures cause considerable overhead for you, the developer. Especially at the time when a project is deliberately confronted with it for the first time.
But as soon as the critical point is exceeded, you will benefit daily and clearly noticeable. Sustainable. The more you invest in advance, the lower the risk of unexpected mistakes. This leads you to be more chilled, that you can work more structured. Your working day becomes more predictable.
Imagine what it will mean to receive the results after running your test suite which indicate that your changes won’t accidentally produce any breaking changes in the code base. Or how it feels to go on vacation with a clear conscience, because your colleague can take over without any problems.
And don’t forget: Good code will automatically increase your reputation in the team as well! ;-)
…for your team?
Did you ever have the job to take over a task of one of your mates? What was your reaction when you first saw his or her code? Did you feel good implementing big changes to it? Has the code been easy to understand or maybe well documented?
You may not have had any negative experiences yet. But let me say one thing: you do not want to be responsible for making changes to a chaotic code base that does not allow you to assess any side effects. Neither your colleagues do!
Thus it is very important to take care of code quality measures like design patterns and guidelines, writing self-descriptive code or at least understandable comments, reducing the complexity of functions and writing as many tests as you can.
Taking care of code quality leads to a certain degree of interchangeability and reduces the degree of specialization. This is usually the reason why a team’s resources can only be deployed half as effectively as it would be possible in a perfect world. Because there will always be less professionals than rookies. This means, the more every single developer invests in code quality the easier for the whole team to switch between tasks, to help each other or to take over someone else’s tasks. Just think about how much faster and easier the work in a team will become. Ka-pow!
…for your company?
Oh, that one is simple. Code quality measures are pretty expensive and not chargeable to the customer. They take too much time, make every little aspect much more complex than necessary and are just annoying overhead…
Not infrequently you get to hear such or similar statements from your project managers, team mates or your boss. Sure, taking care of code quality means effectively more work. But did you ever put the costs of troubleshooting in relation to the costs that are incurred to avoid mistakes? American software engineer and professor of computer science Barry W. Boehm released a book called “The ROI of Software Engineering: Some Quantitative Results for Software-Intensive Systems” back in 2008 which shows a diagram of the relative costs of fixing requirement errors:
As you can see, the costs of fixing software defects explode with the progression of a project’s life cycle. Conversely, this means that errors that will be detected and resolved early can lead to lower costs than if they are being resolved much later. Because code quality itself affects the first steps of life cycle it can save a huge amount of unexpected costs afterwards.
And it also creates a degree of planning certainty, which is essential to keep projects and their processes in the time frame. In theory, this means less overtime for the team, less hassle and less deadline pressure. At least in theory!
…for your customer?
Developers (or whole companies) who work for a customer earn money for what they do. And the customer relies on the result being fully functional. From initial startup to the latest deployment of new features or updates. It’s a matter of reputation that your code or software product works as expected. On any time. It is impossible to imagine what costs will arise for the customer if an unforeseen outage occurs.
But there is one more thing to keep in mind: Suppose you need to program a plugin for the customer’s web store. After the successful launch of the plugin, the customer decides to change to another agency. After a while, adjustments to the plugin might be necessary. At that point it is decided whether the code for which the customer has paid is worth its costs. Because even if it is no longer your customer, the quality of your code still says something about you. And the reputation is ruined faster than it’s set up.
…for the software itself?
Swedish computer scientist and software engineer Ivar Hjalmar Jacobson, who took part creating UML (Unified Modeling Language), once wrote in one of his works:
The second law of thermodynamics, in principle, states that a closed system’s disorder cannot be reduced, it can only remain unchanged or increase. A measure of this disorder is entropy.
This means, as soon as a software is being modified the chance of bugs will increase. The more you work on a software to improve its architecture, to take care of software engineering principles and design patterns, the more complex your software becomes. But if you invest more time and money for code quality measures you reach a more maintainable, secure and reliable software that lasts way longer.
Now, let’s get back to my good old friend John. I’m quite sure that he’s aware of all the things I did write above. But how to convince him that code quality is a matter of courtesy?
Well, code quality starts in a programmers mind! Not even the moment you start typing. Much earlier! Code quality starts with your first cup of coffee in the morning, with a nice little smalltalk to your colleagues and the way you prepare your desk. It depends on how to align yourself and your thoughts. It depends on your mindset. Your mindset further depends on how you feel. And this all might change from day to day. It’s a bit like with the weather, the one day it’s pouring down the other day it’s sunny. Nobody is perfect, neither you are. But believe me when I say that you have a chance to re-align yourself every single day.
Take your time to write code that follows established structures, common principles and a defined ruleset of guidelines or standards. Usually there might exist a so-called Definition of Done in your project scope or even company wide. A set of definitions a team or company agrees to and which has to be fulfilled before your tasks are considered done.
This goes out to you, John: These are not handcuffs or a corset that robs you your freedom and limits you. There are so many things a programmer needs to keep in mind that it’s a pretty helpful gift to have a “DoD” to follow. To consider code quality measures as important is like table manners . Do not think about it, just follow it and you will see that in the end you will benefit from it. As a software developer, as a team member, as a human being.
And John… there will be the day others expect you to improve the code quality of a software you work on. You’d better learn how to deal with it today than tomorrow!
More from me — If you like, please check it out:
Being a better programmer than this morning — some aspects to focus on