Juha-Matti Santala
Community Builder. Dreamer. Adventurer.

Give your commands consistent names

A lot of modern software development involves running different kind of scripts or commands. If you're a Javascript developer, you might use npm run dev to start your development server; if you're a Rust developer, you may use cargo build to build your project; a Django developer may run python manage.py test to run tests.

Giving these things consistent names across your projects (within your team, organization or your personal projects) and wrapping them with tools like make or just can make a big difference in helping the team remember both the commonly used and the rarely run commands.

Discussion around the topic

The idea for this blog post originated from mhoye's toot:

The most common thing I want to say to GitHub projects is "Please use Make".

It's old as dirt and the syntax isn't great, but even in its simplest use being able to reduce a wall of shell copypasta to "make whatever" is such a breath of fresh air.

Get yourself to where "install", "install-devenv", "build" and "run all my tests" are all dead easy, zero chaff, no typos simple. And if you find yourself re-using some long command chain, add it to the makefile and you're done. It is so good.

Greg Wilson shared his set of commands he's using when he's writing book projects in his blog.

Through that discussion, I also found GitHub's Scripts To Rule Them All approach that resonated a lot.

There's more discussion and shared approaches in the discussion section of mhoye's original toot so I recommend checking that out.

Many tools wrapped in one

In my current job, a colleague has built a custom command line tool that wraps all the various scripts and commands we use within a singluar, well-documented user interface.

We use it to manage docker containers, node processes, different tests (with automatic recognition of which test runner to use based on the test path or file being run) and so on. Under the hood, they all use wildly different tools and I'd be the first one to admit I'd forget the commands all the time if I had to remember them. And as a bonus, we don't need to remember in which docker container we need to run certain commands as all that is hidden into the command line tool implementation details.

Naming is documentation

One benefit of this approach is that you need to remember way less commands, especially if working in an environment that has different programmin languages and ecosystems in use. If you can run make test every time instead of remembering npm test, python manage.py test and cargo test and which one to use when, you have one less thing to worry about.

Another benefit is that giving names to things works as documentation. Command line commands are often very low-level implementation oriented so giving them names that mean something in your context packs a punch.

So far I've personally been doing this within projects (for example I use make for my Pokemon TCG Card Viewer Firefox extension) but this discussion sparked the idea to start using this approach more across my personal projects in the future.

Comments

Comment by replying to this post in Mastodon.

Loading comments...

Continue discussion in Mastodon »