Is your source code developer-friendly? Developers talk about user-friendliness of applications all the time, but don’t often think about whether their own source code is user-friendly. Code tends to rot over time. The documentation gets out of date, configuration files change, little “hacks” are put into place… Eventually, it gets so bad it takes days for a new developer to get his environment set up. And along the way, he has to talk to two or three gurus that know all the little tricks to make things work right. As code ages, it becomes less developer-friendly. As developers, it’s our job to counteract that tendency.

It’s pretty easy to assess the developer-friendliness of a code base. A developer who’s never seen your code before should be able to clone your Git repository, run your tests, run your application, and produce a build without any extra help. And the time it takes him to do all of that should be measured in minutes, not hours. Most enterprise code bases probably fail miserably by these standards but I don’t think it’s impossible to live up to them, even with a large code base. And at least they provide a goal to shoot for.

Software tends to change, and it tends to change quickly. Most code bases are probably pretty friendly when they’re first created. Young code bases are simple, so it’s easy to meet all the criteria listed above. And everyone has every intention of keeping it that way. But as code bases grow, they become very complex very fast. In what seems like an instant, the code isn’t developer-friendly anymore. Developers need to be proactive about fighting this trend.

Why is this important?

Developer-friendly code has business value. When your code isn’t developer-friendly, it takes new developers longer to get their environment set up. It also takes seasoned developers longer to keep their environment maintained and up-to-date. Suppose a mid-level engineer drops and breaks his laptop on the way to work and needs to set up his environment from scratch. Will that take him a couple hours or a couple days? Alternatively, suppose a team needs to add some features to a project that hasn’t been touched in a few years. What kind of state was that project left in, and how long will it take the team to create environments to build, test, and deploy the code? The long-term, repetitive costs of code bases that aren’t developer-friendly add up quickly.

How do you fix it?

So, what do you do if you have an older code base that needs a little love and attention?

Write a README

Github has influenced the software development industry in a lot of ways. One subtle influence is that Github really encourages the use of a README.md file at the root of your repository by rendering it on your repository’s Github page. Even if you’re not using Github, including a README.md file in your repository is a great practice. When you have a readme file, developers don’t have to go searching for the documentation - it’s right there next to the code. Because the readme is checked into the repository, it’s version controlled, and can be updated as the code changes. Even if it gets out of date, it’s easy for any developer to fix it, since they already have permissions and know how to make source file changes in the repository. When you’re writing a readme, keep your developer-friendliness goals in mind. A good readme should explain how to run the tests, run the application, and produce a build.

Simplify Your Toolchain

If you create a readme file and it seems way too long, it probably is. The instructions in your readme file should be simple. And if they’re not, it’s a good indication that your process is too complicated. Ideally, there would only be a single command to test your application, a single command to run it, and a single command to deploy it. If any of those steps currently require more than one or two commands, consider creating a shell script (like test.sh). This makes it easy to run the tests without worrying about the complicated bits - and a developer can still inspect the script if he wants to understand what’s actually going on. Short, simple commands are easier for new developers to grasp and faster for experienced developers to use.

Simplify Your Process

If you have a readme file and it’s easy for developers to get things running, you’re already well on your way to improving the developer-friendliness of your code base. But there’s probably still more you can do. Do developers know what they have to do to get their code merged and approved? Many open source projects document that process in a CONTRIBUTING.md file. What about continuous integration? Do you have an automated process to ensure that code passes quality checks before it gets merged into master? Automated test, build, and deployment processes prevent human mistakes while also making your repositories easier to interact with.