Give your commands consistent names
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
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.
Sign up for Syntax Error, a monthly newsletter that helps developers turn a stressful debugging situation into a joyful exploration.