Make Your Source Code Developer-Friendly

Sunday August 19, 2018
Software Development

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.