run.sh

When getting back to an old project (or being introduced to a project for the first time), notes are worth their weight in gold. Especially the "Next note".

But you know what’s even better than a written note?

A shell script!

For this card, I’m using the name run.sh as a placeholder for the entire concept.

Here’s a hypothetical example. When I see a project with files like this:

I might be somewhat interested in foo.txt. But the thing that really catches my attention are the "build", "run", and "test" shell scripts.

I know that those are a little actionable piece of knowledge that I can run right away. Just from the names, I have a general sense of what they’ll do. And when I’m ready, I can crack them open to see exactly they do.

For example, I’ve just returned to my Meow5 repo after leaving it alone for 5 months (aaaaaah!). Here’s a partial list of what I found in there:

There’s a fair number of files. I know the dev logs (log*.txt) are going to be extremely helpful to get me back on track…​

But the biggest helpers were the three shell scripts (*.sh)!

Even though I have absolutely no idea how to run this project or where I left it five months ago, I was able to run it and understand where I left it by running those shell scripts.

When I’m getting going, functioning scripts can be better than any amount of written documentation because they are:

Hey, I like written documentation, but it’s work to absorb technical information by reading. Running a script isn’t work. You can just run it to see what it does. Then, when you’re ready, you can read it.

I guess this is interesting: everyone knows reading code is a lot of work, but a 2-5 line shell script can be less work than reading a prose description of the same process. As with everything in life, "it depends" and "it’s relative".

Oh, and I hope it goes without saying, but these scripts were all written because they’re useful while working on the project. They were not written with the assumption that I’d be re-joining the project after a long hiatus. I never mean to leave a project for 5 months! But it can happen.