Special offer: Maintainable Software Worksheet and free 30-minute consultation! Download

This is part 2 of a 3-part series on maintainable software. We’ll link the other parts as we write them.

What is “maintainable software”?

In our definition, the primary characteristics of maintainable software are:

  • Developers new to the project can start working quickly.
  • Features can be added and changed efficiently.
  • Security patches can be applied quickly and easily.

This post focuses on efficient development; in other words, keeping development costs in line with the scope of changes being made.

Why is efficient development important?

For project stakeholders, the most obvious ramifications are related to development costs and speed. Efficient development minimizes your project’s cost and time-to-market and maximizes its agility, making future iterations of development and maintenance easier and less expensive.

A less obvious outcome of efficient development is that developers will have higher job satisfaction, which will lead to better engagement and retention of developers.

What can I do, as a non-developer, to encourage efficiency?

Your developers may or may not be following the best practices we outline below. To help you get a handle on where you stand, here’s a list of questions you can ask your developers:

  • What percentage of the code is covered by automated tests?
  • Are coding style standards documented and/or enforced?
  • Do you use automated code grading? If so, what is the grade now, and how has it changed over time?
  • How do you feel about deploying changes to production?

Need help?

If you’re frustrated with the effort required to change your application, please get in touch with us, and we’ll help you figure out how to improve the situation.

As a developer, what should I do to make my team efficient?

Embrace change

Believe it or not, a major barrier to development efficiency is fear of change. Developers who are afraid to make changes will tread lightly, leaving “broken windows” in the code alone for fear that fixing them might break something else. The “broken window theory” (one window is broken, and soon after, the neighborhood as a whole is in decline) can be a useful metaphor for maintaining software.

Fear of change is a sure path towards poor code quality and slow development. Developers who fear releasing new code to production may delay releases, causing a larger amount of changes to be released all at once. This slows the feedback loop and increases the risk of each release. Minimizing fear of change is critical to development productivity.

Fortunately, we have a lot of tools we can leverage to alleviate fear of change, including:

  • Version control: Using version control software (e.g. git), means that we can always go back to any previous version of our code. This is an incredible safety net!
  • Automated tests: A thorough, automated test suite can help to find regressions created by code changes. When developers can rely on their test suite, they will work more confidently.
  • Development/staging/production parity: Development, staging, and production environments should be set up as similarly as possible in order to avoid unexpected issues when making releases.
  • Reliable, one-step releases: At Singlebrook, we script our releases so that developers only need to issue a single command to get changes out to staging or production. We endeavor to make our release processes reliable, building in automatic rollbacks in case of errors, and ensuring that releases are all-or-nothing, so that a system cannot be left in a halfway-updated state. Our tools of choice are Heroku for “serverless” hosting and Capistrano for scripting deployments to servers.

Use your time effectively

Developers can go down rabbit holes, getting further and further from the problem they’re trying to solve. Sometimes, this is unavoidable, because software is built on software, which is built on software, etc, and we sometimes have to dig deep to get to the heart of a problem. But, it’s also possible to sidestep a problem by approaching it from a different angle. See also: Yak shaving.

“Bike shedding” is when too much time is spent on trivial decisions. While giving alternative designs their due consideration is often valuable, it’s easy to waste too much time on unimportant decisions. Just make a decision and go for it! The great thing about coding is that we can almost always go back and change a past decision. See also: Parkinson’s Law of Triviality.

Automated code reviews are a great way to save time on code review. (This should not replace human code review, though.) For example, if your team is spending code review time on correcting code style, you should check out Rubocop and get it incorporated into your test suite. This allows your workstations to check your code style (and to automatically correct it, if you choose), saving valuable developer time.

Understandable software is also a key component of efficient development. We talked about this in part 1 of this series, “Easy onboarding of new developers”, so we won’t discuss it further here.

Refactor code to make sure behavior changes are relatively self-contained

Poorly-factored code often results in a developer having to modify several different classes or files in order to effect a single behavioral change. High cohesion between classes or files makes changes more risky. If you have to modify multiple files to change a behavior, it’s more likely that you will adversely affect other parts of the system in unintended ways. The resulting game of whack-a-mole troubleshooting can be very frustrating for everyone (developers, stakeholders, and users).

Uncle Bob Martin’s Single Responsibility Principle says “A class should have only one reason to change.” Using this a guiding principle in your refactoring, and documenting your classes’ single responsibilities at the top of each file, can help you build software in which behavior changes can be made by modifying one (or another very small number) of classes or files.

Having trouble making progress towards efficiency?

If your team isn’t working efficiently, contact us now, and we’ll work with you to move you in the right direction.

Stay tuned for the conclusion of our maintainable software series next week. We’ll be discussing software updates, dependency version constraints, and how to avoid a scramble when the next big zero-day vulnerability is announced.

If you missed it, Part 1 will help teach you to streamline developer onboarding. Up next is Part 3, which is all about quick and easy security patching.