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

• Part 1: Easy onboarding of new developers
• Part 2: Reasonable cost for adding, changing, or removing features
• Part 3: Easy application of security patches

What is “maintainable software”?

In order to discuss how to create maintainable software, we have to start with a definition. For us, the primary characteristics of maintainable software are:

• Developers new to the project can start working quickly.
• Features can be added and changed, with a commensurate level of effort/cost.
• Security patches can be applied quickly and easily.

Today we’re talking about onboarding developers. In other words, how to set up your project so new developers can start working quickly.

Why is this important?

If you’re a project stakeholder, but not a developer, you might be wondering why easy onboarding of new developers is important. Perhaps you have a stable team in place and you’re not planning any personnel changes. Well, as we know, “the only constant is change”, and personnel changes can happen rapidly and unexpectedly, especially in the wild and globalized world of tech!

Enabling easy onboarding of new developers lets you roll with those inevitable changes. If onboarding is difficult, the potential consequences are:

1. You could be stuck with no-one able to work on the project. If you have a small dev team, one person’s illness or a job change can leave you high and dry. You never want to be in a position where making changes to your business-critical software is impossible.
2. The expense of onboarding becomes unreasonably high. This is pretty self-explanatory, but if it takes a long time to get new developers up and running, you’re going to pay for it, both in salaries or consulting fees and in opportunity cost.

As a non-developer, how can I ensure that onboarding is easy?

It can be daunting for a non-developer to ensure that the best practices outlined here are being followed. So, we’ve assembled a list of questions that you can ask your developers to get that conversation started:

• Given a brand new workstation, how long would it take you to get set up?
• Is there step-by-step documentation for the developer setup process?
• Do I have access to the code, the hosting, and any external services that I would need in order to onboard a new developer without your help?
• What automated code quality rating tools do you use? What overall score/grade do they give the application?

Need help?

If you’re not confident that your development team is creating maintainable software, get in touch with us, and we’ll be happy to help guide you.

As a developer, how can I make onboarding easy?

Now that we’re all on the same page regarding the importance of easy onboarding, we can look at the practices that actually enable it.

Simple, reliable development setup

The most important thing for getting a new developer up to speed is a well-documented process for getting set up to work on the application. We keep these instructions with the project code, along with other documentation, so that its always readily available to developers. For most of the applications we work on, a new developer can get set up in an hour or less. Without this crucial documentation, setup can easily take a day or more, wasting time and discouraging new developers from the outset.

Once clear setup documentation is in place, the team can make decisions about how much automation makes sense. There are a variety of ways to automate dev setup, including scripting the process to reduce the number of steps, using container technology (e.g. Docker), or using virtual machines. We tend towards a low level of automation, but we will virtualize apps with complex setup requirements.

Owner has access to code and servers/hosting

In order to work on an application, developers need to be able to access both the code and the servers (or hosting platform if you’re using “serverless” hosting). If you’re working with a freelancer who is hosting your code and your application, it’s far too easy to get locked out of your own application if your freelancer goes AWOL.

The best scenario is that the application owner owns the hosting for both the code and the application. This ensures that the owner can grant access to new developers as necessary, even if their former developers are no longer available. (The new developers should be happy to help with the technical details of this process.)

Many applications also make use of various hosted services, so there may be additional access that the owner needs to cover all bases.

Understandable software

This is a complex topic, so we’ll try to stick to the 10,000-foot view. Some important aspects of understandable software are:

• Consistent terminology: The names used in the code should match the names used when communicating about the software with stakeholders. This minimizes the amount of conversion developers must do when they are talking about, or working on, the code. E.g. if you call your customers “customers” in your speech, don’t call them “users” in the code. Tip: you can create a glossary file for new projects that developers can use for reference.
• Small functions and classes: Developers can learn how a piece of code works more easily if it has clear boundaries and a limited scope. Files with more than a couple hundred lines are hard to read and absorb.
• Useful comments: Too often, developers fail to add any comments to their code. While well-written code should be easy to read, even without comments, we find two types of comments really helpful:
  1. Comments that explain why something is happening (as opposed to those that describe what is happening).
  2. A single top-level comment in each file that describes the file’s responsibility. This practice helps later developers see at a glance what a file is for, and helps the author to keep that file focused on a single responsibility.

There are some great tools available for rating code quality. We’re partial to Code Climate. Good scores from automated rating tools don’t necessarily indicate that your application is maintainable, but bad scores are usually a pretty clear indicator of hard-to-understand code.

Feeling like you need a hand?

If your team needs help in making your software more maintainable, contact us now, and we’ll help get you moving in the right direction.

Stay tuned for the rest of our maintainable software series in the next couple of weeks. We’ll be talking about minimizing fear of change, software updates, and lots more!

Up next: Part 2: Efficient Development