in PHP

The case for maintainable code

Developers and their employers are often at odds over matters like clean or beautiful code and with good reason: neither ships a product or increases sales. Most end users don’t care what the code looks like, as long as the product works and meets their needs. That means that beautiful code goes out the window when the rubber meets the road and crunch time sets in.

The fact of the matter is that framing code discussions in terms of beauty or attractiveness doesn’t help the case for getting code that’s clean. But there’s another way to frame the discussion that makes more sense, and achieves both the goal of writing clean code and meets the needs of most businesses: the concept of maintainable code.

“Maintainable code” is by definition code written with the intention that it will be maintained by someone else, usually someone other than the developer who wrote it. Most developers imagine writing code, sending it into production, and moving on to the next awesome thing they need to do. This simply isn’t the way code works: 70% – 90% of the work developers do is on existing code.

The more convoluted your existing code is, the more difficult it is to maintain. We have a fancy phrase for this problem: technical debt. Technical debt is the accumulation of code that is difficult to maintain and requires dramatic improvement by developers to change it.

Writing maintainable code takes effort, consistent application of standards, and reasonable amounts of thought to the design and structure of the code. How do you write maintainable code?

Maintainable code follows a coding standard.

It stands to reason that maintainable code is code that is easily understood by the developer who comes along after you. And a significant part of understanding and reading code simply lies in the application of a coding standard.

Indentations are often important for logical blocks, and yet even today I see code that doesn’t follow some form of logical indentation. Whitespace-sensitive languages like Python force developers to apply best practices in this area, but PHP does not.

Luckily, there are easily available coding standards right now that can improve your code without too much hassle. PSR-1 and PSR-2 make great coding standards, are incorporated in PHPCS (PHP CodeSniffer), and can be applied automatically in IDEs like PHPStorm.

Maintainable code implements object-oriented best practices.

It’s possible to write procedural code that is maintainable, and I don’t want to get bogged down in an argument of procedural vs. object-oriented here. But even good procedural code will follow some of the best practices of object-oriented development, namely the application of the single responsibility principle. And this is important for maintainable code.

The benefits of object-oriented design for maintainability include the ability to use configuration, not code changes, to alter behavior, plus the ability to make use of well-designed interfaces to extend the application. A well-designed application can change behaviors very quickly, and bugs can usually be isolated to one location in the code and fixed permanently.

Object-oriented code that exhibits maintainability also avoids repeating itself (DRY principle) and instead creates abstractions for concepts that need to be repeated throughout the code base. This limits changes required to modify certain repeated behaviors.

Maintainable code is easily tested.

When writing code that’s maintainable, you also get testability for free. The reason for this is that maintainable code is often easy to mock and examine in isolation, making unit testing possible.

Many developer still struggle with the basics of testing, and in many cases, maintainability is the culprit. Spaghetti code can’t be tested, and most legacy code is poorly written procedural code. This makes testing nearly impossible.

The importance of testing shouldn’t be understated here. Most organizations embrace, at least on a subconscious level, the importance of tests for keeping applications running well. The challenge is that many of them can’t test, because their code is difficult to maintain. And the difficulty in maintaining their code leads to challenges with reliability, adding new features, and ultimately solving business problems.

Maintainable code today, easier maintenance tomorrow

Writing maintainable code today makes maintaining that code easier tomorrow. This might seem like a no-brainer, but it’s an important point: writing maintainable code isn’t about how you write it in the moment; it’s about how you’ll interact with it in six months. It’s important, though often difficult, to have this level of foresight about the code you’re working on, especially with deadline pressures and important business outcomes resting on the work you’re doing. But it’s important, and absolutely worth the effort.

  1. I was just made aware of the PSR-2 guidelines, so its timely for me to stumble upon this great article. I definitely agree that a focus on testing will pave the path for more maintainable code.

Comments are closed.