Compass and map

Lately Jess and I have been talking about the work of software development, particularly project setup.

Some of the work that we do when is purely experimental. “What happens when I push this button?” “What sub-commands are available?” “What is possible with this library?” “Will this fix it?” That’s exploring.

Exploring can be aimless. It can also be deliberate. We can make hypotheses and prove or disprove them. “I don't understand this framework, but I hypothesize that a change to this file will be be reflected in the UI”. This kind of code science can help us build a model: a limited theory of how software works.

This is like looking at the map and saying “I think that I'm here, and if I'm right that means when I walk two hundred yards East-South-East I'll hit a stream”. This is science, but “science” means a lot of different things to different people. So let's call this orienteering.

Exploring is only part of the work. Often we know approximately where we are, we know that a destination exists, and we are trying to get there. “The frob tool should be installed” “There should be customers in the database” This is traveling.

Traveling should be repeatable. It should be reproducible. Traveling should not involve a map and compass and some scribbled notes about “taking a left at the big tree”. The transition between exploring and traveling is accomplished with pathmaking.

Pathmaking can be as rudimentary as trailblazing. (Trailblazing is not as destructive as it sounds. It simply means delineating a path with “blazes”: periodic markings on trees.) This can mean writing a basic README.

Or pathmaking can be more robust, like clearing brush and shoring up a trail with stone stairs and logs for erosion management. This can take the form of of formal documentation, automation scripts, utilities, code generators, and many other conveniences.

The important thing about pathmaking is that the path exists in a known, shared, canonical location. Either the project repository (usually the best place) or a team wiki.

But sometimes we don’t make a conscious distinction between exploring and pathmaking. We get lazy and force other developers (including our future selves!) to repeat the same exploration over and over again. This is traipsing. We expect others to just traipse behind us, without any assistance.

Coding is inherently pathmaking. We figure out what needs to be done and and then we make a path that the computer can follow. Sometimes we even write it such that human readers can skim the individual steps and still see the overall journey. We call this readable code.

Setting up a new development environment for an established project often feels like exploring, but it shouldn’t. It should be traveling.

Jess has been exploring how to use Dockerized development environments to make setup repeatable. After some hesitance I think I’m on board. Computer horsepower is more of a commodity than it used to be, and being able to move a dev environment from one machine to another via checked-in configuration is a clear win.

Another, less implication of the exploring/traveling distinction: Data in development databases should be truly ephemeral and erased often. Is there data that is often useful to have? Then it should be captured in a seeds file, which is checked into the repository.

What are you doing right now? Are you exploring, pathmaking, or traveling?

Published by Avdi Grimm

Leave a Reply

Your email address will not be published. Required fields are marked *