You may be working on a small open source project or on a large corporate team. In either case you will probably have new team members coming in the future. There is much we can do to cut unnecessary overhead in the installation of a new development environment.

Almost anyone of us has been in the situation where it took days to install the development environment for a project we joined. Version control, IDE, libraries and lots of other stuff have to be set up and play together.

We inevitably come across an installation or configuration problem that every other team member had to solve as well. They just can’t help us much because they had to solve that problem exactly once, years ago.

In a slightly better situation, one of the more experienced team members can guide us through the installation of everything. It still takes some time, because they have to download the IDE installer, run it.

Then they contact IT or whoever is responsible to get the license key. Repeat for the version control system. And for those proprietary libraries the team is using. For IDE plugins, access to the build server, bug tracking system,… You get the picture.

How nice would it be if we actually could have everything up and running in a matter of hours or even minutes instead of days?

Package the development environment

There are so many ways how installation can be done in one step these days. We already do it with our own software: We automatically let build and integration servers install and configure our software and accompanying libraries. We even run and test it on a regular basis.

The same can be done with our development environment. There are lots of different approaches. Unpack a zip file and/or run a small shell script. Provide Docker or virtual machine images. It does not matter what you do exactly as long as you automate as much of it as is you reasonably can.

“As much as reasonable” means that there probably are things that can not be automated well. There may for example be an installation wizard that needs some clicking or you need to enter a unique license key.

In a simplistic view, we can divide the actions needed to install our development environment into three categories

1. Stuff that can be done or has to be done before the actual installation even starts. This includes the procurement of hardware and of software licenses, the creation of user accounts and granting the needed right to those accounts.
2. Things that can not be automated. This includes at least one step: “Start the automated installation”.
3. Steps that can be automated.

Before the installation

Everything that can be done before the new user actually starts their work, should be done. The more you have done, the less time the new user needs to wait. Start as early as possible to reduce the risk that anything unforeseen happens.

I have seen people join a company and have to wait several weeks for their laptop. This was a major screw up on different levels that basically caused a few thousand Euros worth of paid boredom and frustration. Not a good start in a new company.

In a good organization the team has a checklist of things a new team member needs before they start. Send that checklist to the people who have to work on it and check that everything is done before the new member starts.

Manual steps

The fact that things have to be done manually does not mean that they have to be passed down by senior team members vocally. Write down a list of detailed instructions how to install the development environment.

When you write down that list for the first time, test it. If you come across inconsistencies, fix them. Put the list under version control, together with the pre-installation checklist. After all, it is a kind of code, even if it is executed by humans.

How can you test “code” like that? Well, if there is a new team member joining, there will usually also be a computer where the “manual installation script” can be tested. Whether a senior team member does the testing or the newcomer is pretty much up to you.

If you let the new team member test the script, tell them that it is untested so they don’t expect everything to work right away. Also make sure that they fix the script as they go.

Automation

Once you have the script for manual installation, it is usually not too hard to automate parts of it. It pretty much boils down to refactoring human-code into something the computer can execute. Seems those techniques can be applied everywhere 😉

How much you should automate depends largely on how many new team members you expect to come. Of course it is not worth to spend days writing the automation scripts when only two or three team members save some hours.

Nevertheless the automation can pay off for small teams, or even if you are working on your own private project and don’t expect others to join in any time soon. If my setup works for me, I tend to use at least a similar development environment for my next project.

I also have a PC at home and a laptop for travels where I like to have the same environment, so I am building a Vagrant box to have the same Linux development environment on both Windows machines. At work, I have another VM with the same libraries and IDE as my team mates.

Convention over configuration

Where people put their programs and how they organize their development environment can be a matter of personal taste. Which way is the “best” can be a topic of heated discussions, similar to coding standards.

Nevertheless, like coding standards, it is also a matter of familiarity. We get used to pretty much anything, and like coding standards, it is good to have a common basis. If we are pair programming or a colleague is simply helping us, they can do so better if they know how the development environment is organized.

That means, do not overload the automated scripts with configurable parameters. Similarly, be specific in the manual script about where to put stuff and how to configure your tools. That also makes it easier for the team to write their own little tools that don’t have to account for all kinds of eventualities.

Conclusion

Now, how does all that fit into this blog’s topic of C++ and Clean Code? Obviously, there is nothing C++ specific. But it is in fact closely related to Clean Code, and not only because I called the manual installation script “human-code”.

The goal of Clean Code is to make the software project maintainable and remove impediments. Having a simple, clean, repeatable and largely automated installation of our development environment makes sure that the very first obstacle we might encounter is as small as possible. It is the best first step to actually get our work done.