I have a folder of scripts I wrote over the last several years. Some of them I run every day. Most of them I have not touched since the week I wrote them. Looking at the two groups, the difference is almost never technical quality.

The scripts that survive share a handful of properties that have nothing to do with how they are written.

The Properties

They solve a problem that recurs

This sounds obvious. It is less obvious in practice. When you are annoyed by something for the third time in a week, it feels like a recurring problem. Sometimes it is. Often the annoyance is transient — you were in an unusual workflow, or the environment changed, or the thing that caused it was a one-off. A script written in that moment solves a problem that does not actually come back.

The scripts I use every day solve problems that have recurred for years: renaming files from camera output conventions, batch-converting something, reformatting a thing that comes in wrong and needs to go out right.

They require no setup to run

The moment a script requires a virtual environment activation, a config file in the right location, a specific working directory, or a dependency that might have drifted — it has a startup cost. Startup costs kill usage.

The most durable scripts I have are single-file, zero-dependency Python or bash. They take arguments. They assume nothing about the environment beyond what is on any machine I use.

#!/usr/bin/env python3
"""
rename-dated.py — Rename files to YYYY-MM-DD_original-name format.


Usage: python3 rename-dated.py *.jpg
"""
import sys
import os
from datetime import date


def rename(path: str) -> None:
    directory, filename = os.path.split(path)
    prefix = date.today().isoformat()
    new_name = f"{prefix}_{filename}"
    new_path = os.path.join(directory, new_name)
    os.rename(path, new_path)
    print(f"{filename} -> {new_name}")


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: rename-dated.py <file> [file ...]", file=sys.stderr)
        sys.exit(1)
    for arg in sys.argv[1:]:
        rename(arg)

No imports beyond the standard library. No setup. Drop it anywhere and run it.

They fail loudly and clearly {#fail-loudly}

A script that fails silently is worse than a script that does not exist. You run it, it appears to succeed, something downstream breaks an hour later, and you spend forty minutes figuring out where the problem originated.

Loud failure means:

  1. Exit with a nonzero code on any error
  2. Print a message that names the file and the problem
  3. Do not try to recover silently
import sys


def process(path: str) -> None:
    if not os.path.exists(path):
        print(f"Error: {path} does not exist", file=sys.stderr)
        sys.exit(1)
    # ...

The error messages do not need to be polished. They need to be specific enough that when you see them six months from now you know what went wrong.

The Test

Before writing a script, I ask two questions:

  1. Will I encounter this problem again in the next three months?
  2. Can I run this script with no more than one command, from any directory, with no setup?

If the answer to either is no, the script probably does not need to exist. Documenting the manual steps might be more useful — documentation is easier to maintain than code you will not run.

The scripts that pass this test are the ones still in active use three years later. The rest are archaeology.

For a related case study in file watching — a pattern that leads to a lot of half-used scripts — see Watching a Folder.